2 年前も最有力として採用した

仕事で詳細設計を書く段取りになりそうなので Markdown 記法ができるドキュメント生成用のパーサは今何があるのか再度調べてみた。 Sphinx の方も Markdown 対応が進んでいるようだが、やはりまだ 2 年前と同様に MkDocs が最有力のようだ。ということで再度調べ直したが、やっぱり便利だ。というより 2 年前に書いた自分の記事が参考になった。自分で調べたことでも半年以上経つとほとんど覚えていない……。

build したファイルをローカルに置いて正しく見る設定

2 年前に調べた時に複数の Markdown ファイルをリンクする構成の場合 index.html へのリンクがうまく張られないという問題があった。今もそうなのかと思って調べたところ、どうも 2 年前に考察したこんなことをしなくても mkdocs.yml への設定一発でできるようになっているようだった。というより当時からできていて私が知らなかっただけなのかもしれない。

mkdocs.yml に以下のようにかく:

use_directory_urls: false

これは stamemo 様の MkDocs で生成したサイトをローカルで開くと index.html が開かれない問題という記事が非常に参考になった。この設定を false にしておくと例えば hoge.md に対して HTML リンクが /hoge のようになってしまいディレクトリ配下の index.html を探索するサーバの挙動を期待するようなリンクの張られ方にならなくなる。 mkdocs パッケージのバージョンにもよるらしいが、私が今試したバージョンだと hoge.html としてビルドされて hoge.html へのリンクが張られた。

今だったらこのような mkdocs.yml にする

site_name: 'サイトネーム'
site_description: 'サイト説明'
site_author: '所有者名'
site_url: 'https://hoge.fuga.com/'
copyright: '著作表記'
use_directory_urls: false

theme:
  name: 'material'
  language: 'ja'
  palette:
    primary: 'cyan'
    accent: 'orange'
  font:
    text: 'BIZ UDPGothic'
    code: 'Consolas'
  features:
    - tabs

plugins:
  - search:
      lang: ja

markdown_extensions:
  - admonition
  - footnotes
  - codehilite:
      linenums: true