コンテナでMkDocs

はじめに

MkDocsについて使い方を書いている記事はいくつもあるので私はこんな感じで使っているという紹介になります。

コンテナ

公開されているMkDocs Materialのイメージを元にちょっと使いたいものを追加します。
バージョンはこれ書いてる時点からすると少し前ですがこの辺は使いたいバージョンで。

PlantUML使うためにPythonパッケージのplantuml-markdownをインストールをしておきます。

Dockerfile

FROM squidfunk/mkdocs-material:9.1.15

COPY user-requirements.txt ./
RUN pip install -U -r user-requirements.txt

RUN apk add bash
RUN apk add zip

user-requirements.txt

plantuml-markdown==3.9.1

ポートは8000を割り振っておきます。
また起動時にserveコマンドを実行することで起動と同時にローカルサーバが立ち上がります。

docker-compose.yml

version: '3'

services:
  mkdocs:
    image: squidfunk/mkdocs-material:9.1.15-add
    build:
      context: .
    container_name: mkdocs
    volumes:
      - ./docs:/docs
    ports:
      - 8000:8000
    command: ['serve', '-a', '0.0.0.0:8000']

下記URLで画面表示を確認できます。
ホットリロードなので変更を入れても再起動は不要です。

http://127.0.0.1:8000/

配布用ファイルの作成

公開する時はサーバに乗せることが多いとは思いますがファイルで配布することもあると思います。
配布用に手動でzipに固めたりするのは手間なのでシェルを用意しておいてこれを実行することで作るようにします。

リリース用ファイルの生成

docker container exec -it mkdocs bash build.sh

mkdocsのbuildコマンドにはオプションを付けておきます。
付けておかないとページ構成にもよりますが、別のページに飛んだ時にファイル一覧の画面が表示されてしまって遷移できません。

build.sh

#!/bin/bash

function compress_archive() {
    mkdocs build --no-directory-urls
    
    mkdir -m 777 temp
    cp -r site/* temp/
    cd temp/
    zip -r ../documents.zip .
    cd ..
    rm -rf temp/
}

compress_archive

MkDocs設定

作図は前述のPlantUMLとMermaidを使えるようにしています。
コードハイライトで行番号表示をするlinenumsは無効にしています。
コードハイライトでコード以外も表示させたいこともあったので基本は無効にしておいて必要な箇所だけ個別に有効化するようにしています。

mkdocs.yml

site_name: Site
copyright: "© 2024 XXX. All Rights Reserved."
repo_url: http://xxx
repo_name: TestRepo
theme:
  name: material  # Material for MkDocs使用
  language: ja    # 日本語
  palette:
    - scheme: default   # ライトテーマ
      primary: green
      accent: purple
      toggle:
        icon: material/brightness-7
        name: ダークテーマに切り替え
    - scheme: slate     # ダークテーマ
      primary: green
      accent: purple
      toggle:
        icon: material/brightness-4
        name: ライトテーマに切り替え
  font:   # フォント
    text: Noto Sans JP
    code: Inconsolata
  features:
    - content.code.copy         # コードコピーボタン有効化
    - content.code.annotate     # コードの注釈有効化
    - content.tabs.link         # コンテンツタブの有効化
    - navigation.tabs           # タブ有効化
    - navigation.tabs.sticky    # タブを常に表示
    - navigation.top            # トップに戻るボタン有効化
nav:
  - トップ:
      トップ: index.md
plugins:
  search:
    lang: 'ja'                  # 日本語検索のみ
extra:
  alternate:                    # 日本語ページのみサポート
    - name: 日本語ページのみサポート
      link: /
      lang: ja
markdown_extensions:
  - tables                      # Markdownテーブルの有効化
  - admonition                  # 警告文拡張 ex)Note, Tip
  - pymdownx.details            # 詳細ブロック拡張 警告文の開閉ができる版
  - footnotes                   # 注釈拡張
  - attr_list                   # 生成されるHTMLに属性追加の拡張
  - md_in_html                  # HTML内のMarkdownをHTMLに変換する拡張
  - pymdownx.keys               # キーコードを装飾する拡張
  - pymdownx.tabbed:            # コンテンツタブ
      alternate_style: true     # コンテンツタブの有効化
  - pymdownx.highlight:         # コードハイライト拡張
      use_pygments: true        # pygmentsの使用を有効化
      pygments_style: monokai   # pygmentsのスタイル
      #linenums: false          # 行番号表示なし(必要なところは個別で指定)
      pygments_lang_class: true # コードの言語に応じたCSSクラスの有効化
  - pymdownx.tasklist:          # タスクリスト拡張
      custom_checkbox: true     # チェックボックスの推奨スタイル有効化
      clickable_checkbox: true  # チェックボックスのクリック有効化
  - plantuml_markdown:          # PlantUML
      server: http://www.plantuml.com/plantuml
  - pymdownx.superfences:       # コードフェンス拡張 コードとか警告文とか色々ネストできるようになる
      custom_fences:
        - name: mermaid         # Mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
extra_css:                      # 追加で読み込むCSS
  - "css/common.css"
  - "https://maxcdn.bootstrapcdn.com/font-awesome/4.6.1/css/font-awesome.min.css" # CDNからFont Awesome読み込みでアイコンを使えるようにする
extra_javascript:
  - "js/common.js" # なんかあれば

ヘッダ部分の見た目

CSS

色や位置等を調整しています。

また、beforeの疑似要素を使って見出し前にアイコン表示しています。
class指定あれば別のアイコンともしています。

common.css

[data-md-color-scheme=default] {
    --md-default-fg-color--light: #222 !important;
}

[data-md-color-scheme=slate] {
    --md-default-fg-color--light: #fefefe !important;
    --md-typeset-a-color: #fc0 !important;
}

/* 見出し */
.md-typeset h1 {
    font-weight: bold;
    border-bottom: solid 2px #f18b21;
    padding-bottom: 5px;
}

.md-typeset h2 {
    border-bottom: 1px dotted #888;
}

[data-md-color-scheme=slate] .md-typeset h2 {
    color: #fc0;
    border-bottom: 1px dotted #888;
}

.tasks h2::before {
    font-family: "FontAwesome";
    font-weight: 500;
    content: "\f0ae";
    margin-right: 5px;
}

.md-typeset h2[class="arrow"]::before {
    font-family: "FontAwesome";
    font-weight: 500;
    content: "\f101";
    margin-right: 5px;
}

/* コードハイライト */
.md-typeset pre {
    color: #f8f8f2;
}

.md-typeset .highlighttable .md-clipboard:before,
.md-typeset .highlighttable .md-clipboard:after {
    color: rgba(240, 240, 240, .8);
}

.md-typeset .highlighttable .md-clipboard:hover:before,
.md-typeset .highlighttable .md-clipboard:hover:after {
    color: rgba(102, 217, 224, 1);
}

.md-typeset .highlighttable .linenos .linenodiv pre {
    line-height: 139%;
}

[data-md-color-scheme=default] .filename span {
    color: #f8f8f2;
}