MkDocs で生成したサイトをローカルで開くと index.html が開かれない問題

たとえば以下のような Markdown を書いてビルドしたとすると、

- [page1へのリンクです](pages/page1.md)

生成したサイトでは「page1へのリンクです」ハイパーリンクが表示され、これをクリックすると page1.md に相当する HTML ページにアクセスできるはずだ。

しかし実際の挙動は、

  • サイトの構造は pages/page1/index.html となっている
  • リンクをクリックした時は pages/page1 という ディレクトリが開かれ、index.html まで開かれない

となる。なぜなのか。

なぜ?

ディレクトリにアクセスした時に index.html を開く、という挙動はウェブサーバーが行っている から。ローカルから生成サイトのファイルにアクセスした場合、当然ならウェブサーバーは動いていないので、この挙動も働かない。

どうすれば開くようになる?

方法1: index.html まで開かれるようにする

mkdocs.yml に use_directory_urls: false を設定することで実現できる。

use_directory_urls が true だと HTML 変換後のリンク先は pages/page1 までとなる。その先の HTML ファイルをどう補わせるかはウェブサーバー任せ。デフォルトだと true。

use_directory_urls が false だと、このお任せは行わず、リンク先は明示的に pages/page1/index.html と index.html を指すようになる。

参考: use_directory_urls - Configuration - MkDocs

方法2: サーバーを立ち上げる

mkdocs serve コマンドでローカルサーバーを立ち上げてから読む。

方法3: どっかにデプロイする

GitHub Pages など、どこかウェブサーバーが稼働してるとこにデプロイしてから読む。

参考