MkDocs

MkDocs で何故か docs_dir の直下にある readme.md が変換されない件

MkDocs 1.0.4 の話。docs_dir で示したディレクトリに index.md と readme.md を置いていると、なぜか readme.md だけビルドの対象にならない。 原因は MkDocs のソースを見てようやくわかった。 index.md が存在する場合、readme.md のパースは無視される …

MkDocs で .git や node_modules など指定ディレクトリを exclude(除外) したい

MkDocs でリポジトリ中の Markdown ファイルたちを HTML に変換したいのだが、.git やら node_modules やら巨大なテンポラリフォルダが邪魔なせいで MkDocs のビルドが終わらない。 exclude できないかと思って、調べて、対処法にたどり着いたのでメモ。 対…

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

たとえば以下のような Markdown を書いてビルドしたとすると、 - [page1へのリンクです](pages/page1.md) 生成したサイトでは「page1へのリンクです」ハイパーリンクが表示され、これをクリックすると page1.md に相当する HTML ページにアクセスできるはず…

MkDocs でスペース2個のインデントをリストのネストとして認識させたい場合

Markdown を HTML 化する手段として MkDocs は有用な選択肢だ。Sphinx の Markdown 版みたいな使い心地である。 しかし唯一残念なのが (リスト等をネストさせる時の)インデントがスペース4個強制 であること。これがスペース2個だと認識されない。 そこでス…

Markdown を HTML で読む手段として MkDocs と MDwiki を試したので優劣を書く

Markdown は書きやすく、そこそこ読みやすい記法だが、それでも plain text なので不便である。定石は HTML に変換して読むことだと思う。で、その変換手段として色々あるんだけど、今回は MkDocs と MDwiki を比較してみる。 前提 記事のまとめ方 MkDocs と…