MkDocsを使って、簡単にドキュメント公開♪

この記事は BrainPad AdventCalendar 2023 14日目の記事です。

はじめに

こんにちは。毎年この時期だけ活動して、なんとなくやっている雰囲気を出すのが得意な@yagizoです。
最近は開発系組織のいろいろなところに首を突っ込んで(いくつかの組織を兼務して)、エンジニアの組織運営を支援したり、エンジニアと他の部署のハブとして奔走したり、既存のプロダクトに新しい武器(機能)を授けるために企画・開発をしたり、新しいサービス企画検討をしたりと、忙しくも充実した日々を送っております。

さて、本題です。

みなさん、開発のドキュメント（APIや機能などプロダクト、サービスの仕様書、説明書）って、何を使って書いていますか？ 私の所属するチームでは、普段 Sphinxを使って、プロダクトのユーザーガイドなどのHTMLドキュメントを作成しているのですが、「Sphinxってなんでもできてとても便利(個人的には最強)なんだけど、ちょっとしたことに使うのには、ちょっと重たいなぁ」と感じていた時に、普段使いに最適なQiitaで馴染み深いMarkdown記法でサクサクとHTMLドキュメントが書けるMkDocsというツール（いわゆる静的サイトジェネレーターの１つ）に出会えたので、推しポイントを踏まえつつ、ご紹介させていただきます。

MkDocsの使い方

やぎぞうがQiitaのアドベントカレンダーのネタをドキュメントプロジェクトとして作っていく過程を例に、説明させていただきます。
この辺りの話を、手元の環境(Mac, python 3.9.6)で、この記事を書きながら動作検証していますw

インストール

pipでサクッと入れます。(※手元では mkdocs 1.5.3 が入りました)

$ pip install mkdocs

プロジェクトの作成

今回は、Qiitaの記事を作成するためのプロジェクトをqiita-yagizo-mkdocsと名付けて作成することにします。
以下のように makedocs new $PROJECT-NAME と実行すると、

$ mkdocs new qiita-yagizo-mkdocs
INFO    -  Creating project directory: qiita-yagizo-mkdocs
INFO    -  Writing config file: qiita-yagizo-mkdocs/mkdocs.yml
INFO    -  Writing initial docs: qiita-yagizo-mkdocs/docs/index.md

サクッとプロジェクトの雛形が作成されます。

qiita-yagizo-docs/
  docs/
    index.md       ... ドキュメントの雛形(Markdown)
  mkdocs.yml       ... MkDocsの設定ファイル(YAML)

雛形の時点で、サンプルドキュメントと設定ファイルが揃っているので、この時点でMkDocsを使ってHTMLドキュメントとして利用できる材料が揃っています。

組み込みの開発サーバー起動

MkDocsにはビルトインの開発サーバーが組み込まれているので、なんとMarkdownで原稿を書きながら、リアルタイムでHTMLドキュメントのプレビューを見ることができるのです！

やぎぞうが社内で業務をする際は、ノートPCに外部ディスプレイを接続した2画面で開発作業をすることが多いので、片側をエディタ(VSCode使ってます)、もう片側をブラウザに設定すれば、公開する状態のドキュメントを見ながら(確認しながら)、文章を書けるという理想的な環境が簡単に手に入るのが、最大の推しポイント。
※Sphinxでドキュメント作る場合、文章を「書くという作業」と(いちいちビルドして生成する工程を挟むので)「確認する作業」が分かれていることに、少なからずストレスを感じていました。

では早速開発サーバーを起動しましょう。

$ cd qiita-yagizo-mkdocs 
$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.19 seconds
INFO    -  [17:21:14] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [17:21:14] Serving on http://127.0.0.1:8000/
INFO    -  [17:21:25] Browser connected: http://127.0.0.1:8000/

ローカルにWebサーバーが立ち上がるので、コマンドに表示されたURL( http://127.0.0.1:8000/ )にアクセスしてみてください。

ブラウザ上に、デフォルトのテーマが適用された状態で雛形(index.md)に描かれた文書が表示されているはずです。
※公式サイトのデザイン

MkDocsを使って気持ちいいトコを体験

ちょうど開発サーバーも立ち上がっていることですし、現在書いているこの記事を反映してみることにします。

• index.md ... Qiitaの原稿を貼り付ける
• mkdocs.yml ... 設定項目site_nameをMy DocsからMkDocsを使って、簡単にドキュメント公開♪に書き換える

おお、簡単に表示できましたね!（当たり前だけど、ちょっと嬉しくないですかw）

ビルド

Markdownで原稿が書き上がったら、ドキュメントを公開するためにHTMLパーツに変換しましょう。
と言ってもmkdocs buildというコマンドを一発実行するだけです。簡単ですね♪

mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /Users/yagizo/work/qiita-yagizo-mkdocs/site
INFO    -  Documentation built in 0.16 seconds

ビルドに成功すると、先ほどのプロジェクトディレクトリ配下にsite/というディレクトリが作成され、必要なパーツが一式収録されます。

例えば、外部にドキュメントを公開したいなら、これらのファイルをAmazon S3に置いてホスティングさせるなどして、簡単に実現することができます。

参考：GitHub Pagesへデプロイ

GitHub Pagesを持っている場合は、直接mkdocsのコマンドmkdocs gh-deployでGitHub Pagesにデプロイできるようです。

開発に組み込む

使い方を見てお気づきの方多いと思いますが、コマンド単位で処理が実行できるので、CIとの相性もよく、ドキュメント管理を開発に組み込むことも容易です。

俺俺ドキュメントに育てる

MkDocsがツールの設計上優れていると感じるのは、Fit to standardな作りになっていることです。
個人的に使いやすいツールとは、

• 最初から使える状態（できるだけ設定せずにやりたいことが初心者でも実現できる）
  • = 運用が簡単である (直感的に組み込める)
    　　- Sphinxはできることめちゃくちゃ多いけど、最初の学習コストが高い
• 基本を抑えたら、自分色に染め上げることができる
  • = 拡張できる
  • Sphinxほど色々できないかもしれないけど、カスタマイズできるのは悪くない

か？という視点で評価しています。
※あることを実現するための道具として、玄人（=ドメイン知識あり）と素人(=ドメイン知識なし)は同じじゃないよねという、やぎぞうの視点で評価

SphinxとMkDocsという２つのツールのユーザーとしては、どちらが優れているかという話をしたいわけでなく、今回のテーマでいうと、自分のドキュメント環境を構築するアプローチに対して、

• 最初からやりたいことが言語化できているから、目的(やりたいこと)を実現する機能を満たしているツールを使って、さっさと完成させる(=Sphinx系アプローチ)
• この分野に対して素人だから、デファクトを学んだ後に自分のやりたい(実現したい)ことに対して、少しずつ近づける(=MkDocsアプローチ)

という２つの攻略法があると思っています。

という前提で、簡単にドキュメント公開できることは、使い方でサクッと分かったので、次にいきましょう。ドキュメントって内容はもちろん大事だけど、見た目がかっこいいと気分上がるじゃないですか。

この章では、MkDocsを使って自分のコンセプトを体現しているドキュメントを作るためのエッセンスを紹介します。

Material Designを知ってますか？

アプリを作る時、最終的に使うヒトに対してどういうインターフェース(UI)を提供するか？ってとても大事ですよね。ヒトがアプリを一貫性を持って使えるように考慮するための仕組みを定義するのがデザインシステムで、システム的には共通の操作を実現するための機能的固まり(コンポーネント)を実装していく必要があります。
その際に迫られる選択が、「世の中にあるコンポーネントライブラリを採用するか、ゼロから始める(自前で作る)か」です。

やぎぞうは自前でそれを用意するほどのスキルがないので前者を選ぶことになるのですが、最近共感しているのがGoogleの提唱するMaterial Designです。
※思わずドヤ感だしましたが、デザイン素人のやぎぞうがこれ以上Material Designを語るのは危険なので、その道の識者(エキスパート)に道を譲りますw

そのMaterial Designを実装した拡張が、MkDocsにあるんだから、使わない手はないでしょう。
ということで、自分色を出す例としての推しポイントを語ろうと思います。

Material for MkDocs のセットアップ

Material for MkDocsはMkDocs向けのMterialです。
※サイトがそもそもかっこいいw
セットアップと言っても、pipでサクッと入るので、記述少なめw

$ pip install mkdocs-material

※やぎぞうの環境では、mkdocs-material(9.4.12)、mkdocs-material-extensions(1.3.1)が入りました

テーマ適用

早速、テーマを適用してみましょう。やることはmkdocs.ymlにちょっと追記するだけ。

site_name: MkDocsを使って、簡単にドキュメント公開♪
theme:
  name: material

すると、簡単にテーマが変わり

もちろん、レスポンシブデザインに対応(デフォルトテーマも対応してるけど、ナビゲーションが上部なのがいまいちかな...)してるので、スマホアクセスもOK。

mkdocs-material で俺っぽくしてみる

ちなみにこのmkdocs-materialのチュートリアルサイト自体がオプションの指定をすると動的にデザインが変わるので、マニュアル見ながら、デザインがどう変わるかを直感的に理解することができます。

今回はやぎぞうのロゴを追加し、カラーテーマをクリスマスっぽい感じに変えてみることにします。

事前にdocsの下に、ロゴを追加(~/qiita-yagizo-mkdocs/docs/img/yagizo-logo.png)を配置し、mkdocs.ymlに下記を追記。

site_name: MkDocsを使って、簡単にドキュメント公開♪
theme:
  name: material
  logo: img/yagizo-logo.png
  palette:
    primary: pink

すると、ご覧の通り

簡単にデザインを変えていくことができます。すごくないですか？

mkdocs-material のここスゴイ！

mkdocs-materialの推しポイントをいくつか紹介します。

ブログサイト簡単に作れる

エンジニアがとりあえず自分の技術を他に啓蒙するために、ブログ立ち上げるじゃないですかw
コイツを使うと、アーカイブやカテゴリのインデックス、ポストスラッグ、設定可能なページネーションなどを自動的に生成してくれるんで、コンテンツに集中できます。

GA4によるサイト分析

自分のサイトがどのように使われているか知りたいじゃないですか。
コイツを使うと、Google Analyticsを使って簡単にサイト分析できます。

コメント追加

記事に対してのコメントを、フッターに任意のコメントシステムを指定して追加することができます。

俺俺に染めるためにまだまだ機能が色々ありますが、そちらは公式ドキュメントを自身が攻略する楽しみとして、残しておきますね（サボっているだけともいうw）

まとめ

いかがだったでしょうか？
この記事を読んで、MkDocsを使ってみたくなった方がいたら、やぎぞう的にはコミュニティに対して幾らかの義理が果たせたということで、嬉しいです♪

最後に、MkDocsとSphinxというツールの選定ポイントをやぎぞう視点で比較したチートシートを置き土産に今回の記事を締めようと思います。

検討ポイント	MkDocs	Sphinx
ドキュメント作成について、ざっくり自分は	初心者である	玄人だと思っている
機能	△ (Sphinxに比べると、控えめであるが少ないわけではない)	○
記法(表現力)	△　Markdown	○　reStructuredText (reST)、Markdownなど豊富 (MarkdownでできることはreSTでできるので、reSTがMarkdownでできることを内包している感じ)
設定	○ （初期設定が少なく動く。必要に応じてどんどん設定を追記するスタイル）	△ （設定項目はMkDocsより多めで、理解する必要があり）
開発しやすさ	○ (開発サーバーを起動することで、アウトプットデザインを見ながら確認できる)	△ （ビルドしないと出力結果が確認できない）
デプロイしやすさ	○　（どっちもコマンドで実行できる）	○
拡張性	○　（オープンソースだし、本気出せばそんなに変わらんはず）	○

ではでは、また！

参考

参考にしたサイトをあげておきます。

• MkDocs ... https://www.mkdocs.org/
  • 本家。このサイト自身がMkDocsを使って構築されており、そのコードがGithubで公開されているので、テクニックを学びたかったら、「Webページ見て、コード見て真似る」ができる最強の教本です
  • ちなみに、トップページのFeaturesをMarkdownでどうやって書いているの？を知りたくて見たら、HTML構造剥き出しでゴリゴリに書いている(Markdownでは実現できない)というw
    • 究極のカスタマイズ例がトップページから入っていることを学べるw
• Material for MkDocs ... https://squidfunk.github.io/mkdocs-material/
  • 簡単に俺色に染める最強のテーマ