Skip to content

MkDocsでページを跨って連番を割り当てる

以前にMkDocsで自動的に見出しへ連番を割り当てるというメモを書きました。これ以外にもMkDocsにmkdocs-enumerate-headings-pluginを追加すると見出しに連番を割り当てることができます。しかも同じページ内だけではなく、異なるページも加味した上で連番を割り当てることができます。GitHubのFeaturesには以下の記載があります。

  • Automatically number all headings and (optionally) give each page an sequential chapter number
  • Great for writing (technical) reports
  • Compatible with plugins like awesome-pages and monorepo
  • Compatible with markdown_extensions like pymdownx.snippets
  • Compatible with themes like mkdocs-material
  • Easy to customize styling through CSS

今回はこのプラグインを実際に試してみます。

検証環境

対象 バージョン
macOS 15.6.1
mkdocs 1.6.1
mkdocs-material 9.6.19
mkdocs-enumerate-headings-plugin 0.6.2

テストサイトの構造

テストサイトのディレクトリ構造は以下の通りです。

├── docs
│   ├── 001.md
│   ├── 002.md
│   ├── 003.md
│   └── index.md
└── mkdocs.yml

003.mdファイルは以下の内容です。

003.md
# Level1

## Level2a

### Level3a

#### Level4a

## Level2b

### Level3b

### Level3c

#### Level4b

見え方

MkDocsの設定ファイルである`mkdocs.yml'を以下のように定義したとします。

mkdocs.yml
site_name: My Docs
theme:
  name: material
  features:
    - toc.integrate
plugins:
  - search:
  - enumerate-headings:
      toc_depth: 6
      exclude:
        - index.md
nav:
  - Top: index.md
  - Topic1: 001.md
  - Topic2: 002.md
  - Topic3: 003.md

この設定では以下のように表示されました。excludeでindex.mdを除外している為、このファイルは連番の割り当てから除外され、001.mdから連番が割り当てられています。

image

toc_depthの効果

toc_depthは「ナビゲーション上でどのレベルまで連番を表示するか」を制御します。但し、ページ内の見出しはこの設定に関わらず、連番が割り当てられます。以下の例ではtoc_depthを2に設定しています。

mkdocs.yml
site_name: My Docs
theme:
  name: material
  features:
    - toc.integrate
plugins:
  - search:
  - enumerate-headings:
      toc_depth: 2
      exclude:
        - index.md
nav:
  - Top: index.md
  - Topic1: 001.md
  - Topic2: 002.md
  - Topic3: 003.md

この設定では以下のように表示されます。ナビゲーション上、レベル2までだけ、連番が割り当てられています。本文内の見出しは連番が割り当てられたままです。

image