MkDocsでマニュアルを作る #3 コンテンツ作成 — コードブロック、Mermaid、admonition

フレームワーク MkDocs Documentation Static Site
読了 3分

#2でnavと検索を使ってドキュメントの骨組みを整えました。次はその中身を埋める番です。技術ドキュメントは文章だけでは足りません。コマンドはコードブロックで、流れは図で、注意点は目立つ箱で見せてこそ、読者が素早く読めます。

今回のシリーズはMkDocsでマニュアルを作る全6回です。

  • #1 インストールから最初のドキュメントまで
  • #2 navと検索 — ドキュメントの情報構造を整える
  • #3 コンテンツ作成 — コードブロック、Mermaid、admonition ← この記事
  • #4 Cloudflare Pagesでデプロイしてドメインをつなぐ
  • #5 多言語とバージョン管理
  • #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

この記事では、コードブロックをきちんと装飾し、Mermaidで図を描き、admonitionで強調するという3つを扱います。これらの機能はほとんどがマークダウン拡張でオンにするので、まずそこから設定します。

マークダウン拡張をオンにする #

Materialの豊かな表現はpymdownx拡張から生まれます。mkdocs.ymlに必要な拡張を登録します。

mkdocs.yml — マークダウン拡張 
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

theme:
  name: material
  features:
    - content.code.copy   # コードブロックのコピーボタン

コードブロック — タイトルと行ハイライト #

コードフェンスの言語の後ろにオプションを書いて、タイトルとハイライトを足します。

コードブロックにタイトルを付ける 
```python title="app.py" hl_lines="2" linenums="1"
def add(a, b):
    return a + b  # この行がハイライトされます
```

titleでファイル名の帯を、hl_linesでハイライトする行を、linenumsで行番号を指定します。コピーボタンは、上でオンにしたcontent.code.copy機能がすべてのコードブロックに自動で付けてくれます。

図 — Mermaid #

Mermaidは図をコードで書きます。テキストなのでGitでバージョン管理ができ、直すのも簡単です。MkDocsではsuperfencesにMermaidを登録すればよいです。

mkdocs.yml — Mermaidの有効化 
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

これでmermaidフェンスを開くと、実際の図としてレンダリングされます。

Mermaidフローチャート 
```mermaid
flowchart LR
  A[記事作成] --> B[ビルド] --> C[デプロイ]
```

admonition — 注意と警告の強調 #

「これは必ず読んでほしい」という内容は、文章の中に埋もれてはいけません。admonitionは強調の箱を作ります。!!!の後ろに種類を書き、内容をインデントで入れます。

admonitionを書く 
!!! warning "注意"
    本番に適用する前に、必ずバックアップを先に取ってください。

種類にはnote、tip、warning、dangerなどがあり、それぞれ色とアイコンが違うので、情報・注意・危険を視覚的に区別できます。???で書くと、折りたたみと展開ができる箱になります。

タブで分ける #

OSごとのコマンドのように枝分かれする内容は、タブが便利です。上でオンにしたpymdownx.tabbedで作ります。

タブで分ける 
=== "macOS"
    brew install our-product

=== "Windows"
    winget install our-product

まとめ #

この記事では、タイトルと行ハイライトが付くコードブロック、コードで管理するMermaidの図、そして注意・警告を強調するadmonitionとタブまで扱いました。ここまで来ると、ローカルで見栄えのよいドキュメントが整います。

次回は、このドキュメントを世に送り出します。Cloudflare Pagesでデプロイしてカスタムドメインをつなぎ、誰もがアドレスでアクセスできるようにする過程を整理します。

X