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
# こんにちは! 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に以下の記述を追加します。
theme:
name: 'material'
language: 'ja'
extra:
search:
language: 'ja'
保存して、mkdocs serve
でどうなったのか見てみます。
エモい・・・!
デザインセンス皆無の私にもこんなシャレオツなドキュメントが書けるなんて。
mkdocs.ymlには結構色んな設定が出来るので、公式サイトや各テーマのサイトを確認してください。
締め
普段、wikiなんかはMarkdownで書く事が浸透してきていますが、外部へ提供するドキュメントだったりはWordがまだ使われているところもあるかと思います。
MkDocsでマニュアル作成をすると、作成/修正が手軽で、Githubでも管理が出来、上手くやればオンラインでの自動テストも可能です。なんて便利。
ドキュメントを作成する際は検討してみてはいかがでしょうか。
Author And Source
この問題について(Markdownでドキュメントが作れるMkDocsが便利過ぎる), 我々は、より多くの情報をここで見つけました https://qiita.com/ajitator/items/aec49127f542eac31ffe著者帰属:元の著者の情報は、元のURLに含まれています。著作権は原作者に属する。
Content is automatically searched and collected through network algorithms . If there is a violation . Please contact us . We will adjust (correct author information ,or delete content ) as soon as possible .