Markdownでドキュメントが作れるMkDocsが便利過ぎる

何番煎じだろうと書く。

顧客向けマニュアルをMarkdownで作りたい

ここ最近、社内で利用する仕様書だったり手順書だったりはCrowiでMarkdownで書いています。Markdown、手軽で便利ですよね。

ただ、お客様に提出するような製品仕様や製品マニュアルを公開するのは、セキュリティとかアカウント管理とかの関係でちょっと公開するのはいかがなものかなと。
記事のエクスポート機能でもあればなーと思っていたところで、MkDocsに出会いました。割と感動したので、この感動を皆様と共有したく。

公式サイト

何が凄いのか

• Markdownでドキュメントが書ける
• webサービスを内蔵しているので、わざわざwebサーバーを立てなくてよい
• webサービスはMarkdownへの変更をリアルタイムに反映してくれる
• テーマが選択できるのでデザインセンスがなくても割といい感じにしてくれる
• 1コマンドで静的サイトをビルドしてくれる
• つまり、オンラインマニュアルにもローカル用マニュアルにも両方対応出来る

導入手順

1. pythonとpipのインストール

使っている環境で違うのでマニュアルに従ってインストール
Python
pip

2. MkDocsのインストール

$ pip install mkdocs

3. mkdocs new <プロジェクト名>で新しいプロジェクトを作成する

$ cd project-dir
$ mkdocs new my-project
INFO    -  Creating project directory: my-project 
INFO    -  Writing config file: my-project/mkdocs.yml 
INFO    -  Writing initial docs: my-project/docs/index.md 

これで必要なファイルが自動で作成される

4. mkdocs serveでMkDocsの開発用サービスを立ち上げる

$ cd my-project
$ mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
[I 190807 16:52:48 server:296] Serving on http://127.0.0.1:8000
[I 190807 16:52:48 handlers:62] Start watching changes
[I 190807 16:52:48 handlers:64] Start detecting changes

5. ブラウザで確認する

http://localhost:8000で確認できました。素敵。

修正手順

Markdownを修正してみる

# Welcome to MkDocs -> こんにちは！ MkDocs

my-project/docs/index.md

# こんにちは！ MkDocs 

For full documentation visit [mkdocs.org](https://mkdocs.org).

## Commands

・・・

保存してブラウザを確認してみると・・・

保存するとリアルタイムで反映されているのがわかります。Markdownを利用している以上、リアルタイムプレビューが当たり前なので、これは嬉しいですね。

htmlを出力する

個人的にこれがMkDocsの真骨頂だと思います。
Markdownで作ったサイトはmkdocs buildで静的サイトへ変換が可能です。

# my-project以下で
$ mkdocs build

ビルドすると、docsフォルダと同じ階層にsiteフォルダが作成されて、htmlに変換した結果が保存されます。
試しにsite/index.htmlを開いてみると・・・

先ほど修正したページが出力されている事がわかります。

テーマを変更する

テーマを変更する際はpipでお好みのテーマをダウンロードし、mkdocs.ymlで設定を変更できます。
個人的にはmaterialテーマが好きなので、materialをダウンロードして設定します。ドキュメント内検索が日本語で出来るので大変エモいです。

$ pip install mkdocs-material

mkdocs.ymlに以下の記述を追加します。

mkdocs.yml

theme:
  name: 'material'
  language: 'ja'
extra:
  search:
    language: 'ja'

保存して、mkdocs serveでどうなったのか見てみます。

エモい・・・！
デザインセンス皆無の私にもこんなシャレオツなドキュメントが書けるなんて。

mkdocs.ymlには結構色んな設定が出来るので、公式サイトや各テーマのサイトを確認してください。

締め

普段、wikiなんかはMarkdownで書く事が浸透してきていますが、外部へ提供するドキュメントだったりはWordがまだ使われているところもあるかと思います。

MkDocsでマニュアル作成をすると、作成/修正が手軽で、Githubでも管理が出来、上手くやればオンラインでの自動テストも可能です。なんて便利。

ドキュメントを作成する際は検討してみてはいかがでしょうか。