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 など、どこかウェブサーバーが稼働してるとこにデプロイしてから読む。