MkDocs に入門する
WebMkDocs
2023-2-23 10:27 JST

MkDocs を使い始めた。Sphinx はちょっと使ったけどだめな感じだった。

Sphinx より MkDocs

MkDocs に先立ち Sphinx を使ってみた。結論から言うと、もう Sphinx は使う必要がない。Read The Docs も MkDocs に対応しているので、わざわざ Sphinx にする必要はない。

MkDocs Sphinx
出力フォーマット HTML,PDF,ePubなど HTML,PDF,ePub,man,Texinfo,LaTeX,テキストファイルなど
HTMLのビルドと確認 静的に HTML をビルド+動的に確認可能 静的に HTML をビルド+別途ウェブサーバなどで確認
拡張性 可能(プラグイン) 可能(拡張機能)
テーマ 変更可能 変更可能
ドキュメントの書き方 MarkDown 記法(独自) reStructuredText 記法(独自)
Read The Doc 対応 可能 可能

一番の違いは MD か reStructuredText かということ。reStructuredText 悪くないんだけど(MD よりは好み)、世の中的にはもうオワコンに近い気がするな。特にエディター初心者には MD の方が圧倒的に良い。

Python のドキュメント環境としてのみ Sphinx に一日の長があるかもしれないがC や C++ では Sphinx に全く強みなし。その上、Sphinx はちょっと難しいことをしようとすると途端にわからなくなる。

そもそも MkDocs て何よ

Markdownでドキュメントを書いて静的サイトを生成するPythonのパッケージです。MkDocsを使うことで、高品質で美しく見栄えのするWebサイトを簡単に作成できます。


インストール

まず、MkDocsをインストールします。あとなんだよくわからいけど mkdocs-material も入れておきます。ついでにわたしは mkdocs-asy も入れました。

$ pip install mkdocs
$ pip install mkdocs-material
$ pip install mkdocs-asy

プロジェクトの作成

MkDocsでウェブサイトを作成するためのプロジェクトを作成します。MkDocsを使用するフォルダに移動し、以下のコマンドを入力してください。

$ mkdocs new my-docs

これにより、my-projectという名前の新しいフォルダが作成され、MkDocsのプロジェクトが初期化されます。my-projectの中には、docsフォルダとmkdocs.ymlファイルが含まれています。


ドキュメントを書く

docsフォルダの中に、index.mdという名前のファイルが生成されています。このファイルを開いて、Markdownでドキュメントを書来ます。

index.md
# タイトル

これはサンプルのドキュメントです。

## セクション

これはセクションのテキストです。Lorem ipsum dolor sit amet, consectetur adipiscing elit.

### サブセクション

これはサブセクションのテキストです。Nullam commodo, nulla at molestie efficitur, magna quam varius augue, vel facilisis libero enim ut erat.

プレビュー

プレビューしてみます。ターミナルを開き、my-docsフォルダに移動し、mkdocs serveコマンドを入力します。これにより、ウェブサーバがローカルホスト上で開始されるので、ブラウザで表示可能になります。サイトのURLは、http://localhost:8000 です。この時点ではまだ build されていません。


テーマの変更

MkDocsにはプリセットのテーマが用意されていますが、別のテーマを適用することもできます。theme に readthedocs を設定し、language に ja を設定します。

mkdocs.yml
site_name: MYDOCS

theme:
    name: 'readthedocs'
    language: 'ja'

nav:
    - Top: index.md

ビルド

MkDocs では最終的に HTML のドキュメントを生成します。つまり、nginx などで使用可能な静的な HTML のページ群を作ることになります。

$ mkdocs build

build により site ディレクトリにHTMLファイルが出力されます。後、GitHub に gh-deploy することが可能みたいね。そうすると、GitHub Pages で公開する、、、なんてことが出来るみたい。

リンク集