ドキュメントをマークダウンで書ける時代がやってきた
オフィスソフトでのドキュメント管理はもう嫌だ！
システム開発やサイト制作をしている際、必ず仕様書や設計書を作成し場合によっては納品する必要がありますよね。
昨今では、基本的にExcelやPowerPoint、GoogleスプレットシートやGooleスライドで作成や保守をする事が多いと思いますが、
これがまた悪い文化
何ですよねorz
何が悪いって、シート毎にレイアウトがバラバラになるので統一感が持てない点や修正差分が分かりにくい点に不満を感じます。
もちろん、ある程度の履歴機能やテンプレートはありますが、それでもまだ使いにくい感は否めません。。。orz
Markdownで書けるドキュメントツールを発見
そんな最中、マークダウンでドキュメントを書けるという神ツールを見つけました！
Overview MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introduction below, then check the User Guide for more info.MkDocs
このツールを使えば、Markdownベースでドキュメントを記述出来るため、git管理対象として保守する事が可能になります。
またHTML形式やPDF形式にも出力する事が可能なようなので、納品対応にも対応出来るため期待が出来るツールとなっています！
そして何より、デザインやレイアウトのカスタマイズ性が高いのもMkDocsの魅力とも言えるでしょう。
今回は早速インストールをして基本的な部分の使い方を試してみようと思います♪
細かい機能やレイアウト調整については以下の記事にてご紹介しているので、興味のある方はそちらも読んでいただければなと思います♪
関連記事
【ドキュメントをMarkdownでGitHub管理】MkDocsで生成されるHTMLのレイアウトをカスタマイズする方法まとめ【グッバイExcel・PowerPoint】
IT
Github
Mac
Python
Windows使い方
前提
MkDocsはPythonを利用して動かすツールとなっています。
今回は以下の環境にて動作を確認しています。
- Python 3.6.3
- Anyenv 1.1.1
関連記事
【JavaやRuby含めほとんどの言語に対応】Homebrewで「anyenv」をインストールしてhodenvを使ってバージョン管理をする方法まとめ【fish shellも対応】
IT
Java
Mac
Python
アプリケーションインストール
以下のコマンドでMkDocsをインストールしてください。
Collecting mkdocs
Downloading https://files.pythonhosted.org/packages/5d/89/ed04b217404bbba031c4e2e084f36ef840b8663fce0b80302b547e651e4d/mkdocs-1.1.2-py3-none-any.whl (6.4MB)
100% |████████████████████████████████| 6.4MB 239kB/s
Collecting Jinja2>=2.10.1 (from mkdocs)
Downloading https://files.pythonhosted.org/packages/30/9e/f663a2aa66a09d838042ae1a2c5659828bb9b41ea3a6efa20a20fd92b121/Jinja2-2.11.2-py2.py3-none-any.whl (125kB)
100% |████████████████████████████████| 133kB 2.9MB/s
Collecting Markdown>=3.2.1 (from mkdocs)
Downloading https://files.pythonhosted.org/packages/a4/63/eaec2bd025ab48c754b55e8819af0f6a69e2b1e187611dd40cbbe101ee7f/Markdown-3.2.2-py3-none-any.whl (88kB)
100% |████████████████████████████████| 92kB 3.0MB/s
Collecting lunr[languages]==0.5.8 (from mkdocs)
Downloading https://files.pythonhosted.org/packages/15/a4/3043c019613a1d60abb6e150b7665761bdd236a0d915d447d21c4415fddd/lunr-0.5.8-py2.py3-none-any.whl (2.3MB)
100% |████████████████████████████████| 2.3MB 292kB/s
Collecting tornado>=5.0 (from mkdocs)
Downloading https://files.pythonhosted.org/packages/95/84/119a46d494f008969bf0c775cb2c6b3579d3c4cc1bb1b41a022aa93ee242/tornado-6.0.4.tar.gz (496kB)
100% |████████████████████████████████| 501kB 567kB/s
Collecting click>=3.3 (from mkdocs)
Downloading https://files.pythonhosted.org/packages/d2/3d/fa76db83bf75c4f8d338c2fd15c8d33fdd7ad23a9b5e57eb6c5de26b430e/click-7.1.2-py2.py3-none-any.whl (82kB)
100% |████████████████████████████████| 92kB 939kB/s
Collecting livereload>=2.5.1 (from mkdocs)
Downloading https://files.pythonhosted.org/packages/b5/a2/a36af515c73fac8d596b5e0f1f9b38b83a9366facb3959dd8428727cc650/livereload-2.6.2.tar.gz
Ignoring tornado: markers 'python_version == "2.7"' don't match your environment
Collecting PyYAML>=3.10 (from mkdocs)
Downloading https://files.pythonhosted.org/packages/64/c2/b80047c7ac2478f9501676c988a5411ed5572f35d1beff9cae07d321512c/PyYAML-5.3.1.tar.gz (269kB)
100% |████████████████████████████████| 276kB 791kB/s
Collecting MarkupSafe>=0.23 (from Jinja2>=2.10.1->mkdocs)
Downloading https://files.pythonhosted.org/packages/f0/00/a6aea33f5598b080b86d6b6d1214b51afe3ffa6100b902d5aa465080083f/MarkupSafe-1.1.1-cp36-cp36m-macosx_10_6_intel.whl
Collecting importlib-metadata; python_version < "3.8" (from Markdown>=3.2.1->mkdocs)
Downloading https://files.pythonhosted.org/packages/8e/58/cdea07eb51fc2b906db0968a94700866fc46249bdc75cac23f9d13168929/importlib_metadata-1.7.0-py2.py3-none-any.whl
Requirement already satisfied: six>=1.11.0 in /Users/blogenist/.anyenv/envs/pyenv/versions/3.6.3/lib/python3.6/site-packages (from lunr[languages]==0.5.8->mkdocs)
Collecting future>=0.16.0 (from lunr[languages]==0.5.8->mkdocs)
Downloading https://files.pythonhosted.org/packages/45/0b/38b06fd9b92dc2b68d58b75f900e97884c45bedd2ff83203d933cf5851c9/future-0.18.2.tar.gz (829kB)
100% |████████████████████████████████| 829kB 742kB/s
Collecting nltk>=3.2.5; python_version > "2.7" and extra == "languages" (from lunr[languages]==0.5.8->mkdocs)
Downloading https://files.pythonhosted.org/packages/92/75/ce35194d8e3022203cca0d2f896dbb88689f9b3fce8e9f9cff942913519d/nltk-3.5.zip (1.4MB)
100% |████████████████████████████████| 1.4MB 536kB/s
Collecting zipp>=0.5 (from importlib-metadata; python_version < "3.8"->Markdown>=3.2.1->mkdocs)
Downloading https://files.pythonhosted.org/packages/b2/34/bfcb43cc0ba81f527bc4f40ef41ba2ff4080e047acb0586b56b3d017ace4/zipp-3.1.0-py3-none-any.whl
Collecting joblib (from nltk>=3.2.5; python_version > "2.7" and extra == "languages"->lunr[languages]==0.5.8->mkdocs)
Downloading https://files.pythonhosted.org/packages/b8/a6/d1a816b89aa1e9e96bcb298eb1ee1854f21662ebc6d55ffa3d7b3b50122b/joblib-0.15.1-py3-none-any.whl (298kB)
100% |████████████████████████████████| 307kB 750kB/s
Collecting regex (from nltk>=3.2.5; python_version > "2.7" and extra == "languages"->lunr[languages]==0.5.8->mkdocs)
Downloading https://files.pythonhosted.org/packages/b8/7b/01510a6229c2176425bda54d15fba05a4b3df169b87265b008480261d2f9/regex-2020.6.8.tar.gz (690kB)
100% |████████████████████████████████| 696kB 685kB/s
Collecting tqdm (from nltk>=3.2.5; python_version > "2.7" and extra == "languages"->lunr[languages]==0.5.8->mkdocs)
Downloading https://files.pythonhosted.org/packages/46/62/7663894f67ac5a41a0d8812d78d9d2a9404124051885af9d77dc526fb399/tqdm-4.47.0-py2.py3-none-any.whl (66kB)
100% |████████████████████████████████| 71kB 1.6MB/s
Installing collected packages: MarkupSafe, Jinja2, zipp, importlib-metadata, Markdown, future, click, joblib, regex, tqdm, nltk, lunr, tornado, livereload, PyYAML, mkdocs
Running setup.py install for future ... done
Running setup.py install for regex ... done
Running setup.py install for nltk ... done
Running setup.py install for tornado ... done
Running setup.py install for livereload ... done
Running setup.py install for PyYAML ... done
Successfully installed Jinja2-2.11.2 Markdown-3.2.2 MarkupSafe-1.1.1 PyYAML-5.3.1 click-7.1.2 future-0.18.2 importlib-metadata-1.7.0 joblib-0.15.1 livereload-2.6.2 lunr-0.5.8 mkdocs-1.1.2 nltk-3.5 regex-2020.6.8 tornado-6.0.4 tqdm-4.47.0 zipp-3.1.0
確認
以下のコマンドで確認してみましょう。
mkdocs, version 1.1.2 from /Users/blogenist/.anyenv/envs/pyenv/versions/3.6.3/lib/python3.6/site-packages/mkdocs (Python 3.6)
無事にインストールされていますね♪
プロジェクトの作成
まずはプロジェクトを作成しましょう。
mkdocs new {プロジェクト名}で作成する事が可能です。
INFO - Creating project directory: sample
INFO - Writing config file: sample/mkdocs.yml
INFO - Writing initial docs: sample/docs/index.md
すると以下の形でディレクリが生成されます。
.
└── sample
├── docs
│ └── index.md
└── mkdocs.yml
2 directories, 2 files
以降の作業は生成されたディレクトリに移動した上で行う事になります。
ローカルでの開発サーバ起動(Serve)
では、一旦初期の状態でMarkdownから生成されるHTMLを確認してみましょう。
デフォルトではindex.mdには以下の記述がされています。
# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
## Commands
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.
## Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
以下のコマンドでローカルに開発サーバを起動出来ます。
mkdocs serve 火 6/30 19:36:32 2020
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.09 seconds
[I 200630 19:37:47 server:334] Serving on http://127.0.0.1:8000
INFO - Serving on http://127.0.0.1:8000
これでhttp://localhost:8000/ にサーバが起動されHTMLが確認出来ます。
ホットリロード標準完備が便利過ぎる！
そしてこの開発サーバはホットリロードに対応しているので、サーバ起動後にMarkdownを変更すると自動で再リロードがかかります。
毎回再起動する必要なく、作業者はMarkdownの修正だけ気にすれば良いのはとても楽ですね！
[I 200630 19:43:22 watcher:111] Running task: builder (delay: None)
INFO - Running task: builder (delay: None)
INFO - Building documentation...
[I 200630 19:43:22 handlers:95] Reload 2 waiters: /Users/blogenist/Develop/local/python/mkdocs/sample/docs/index.md
INFO - Reload 2 waiters: /Users/blogenist/Develop/local/python/mkdocs/sample/docs/index.md
[I 200630 19:43:22 handlers:135] Browser Connected: http://localhost:8000/
INFO - Browser Connected: http://localhost:8000/
[I 200630 19:43:22 handlers:135] Browser Connected: http://localhost:8000/
INFO - Browser Connected: http://localhost:8000/
ページを追加
ドキュメントのページを追加する際には、docs配下にmdファイルを追加するだけで自動で反映されます。
## About
This is About Page.
ページ名を制御
ページ名を変えたい場合や順番を変えたい場合は以下のようにmkdocs.ymlに記述する事で制御する事が可能です。
site_name: My Docs
pages:
- Page1: home.md
- Page2: about.md
ちなみに、docs/index.mdはトップページに該当するので用意しておく必要があります。
HTMLの生成(ビルド)
では、実際にHTML出力をしてみましょう。
INFO - Cleaning site directory
INFO - Building documentation to directory: /Users/blogenist/Develop/local/python/mkdocs/sample/site
INFO - Documentation built in 0.12 seconds
すると、siteディレクトリが生成され、HTMLファイル一式が出力されています。
.
├── docs
│ └── index.md
├── mkdocs.yml
└── site
├── 404.html
├── css
│ ├── base.css
│ ├── bootstrap.min.css
│ └── font-awesome.min.css
├── fonts
│ ├── fontawesome-webfont.eot
│ ├── fontawesome-webfont.svg
│ ├── fontawesome-webfont.ttf
│ ├── fontawesome-webfont.woff
│ ├── fontawesome-webfont.woff2
│ ├── glyphicons-halflings-regular.eot
│ ├── glyphicons-halflings-regular.svg
│ ├── glyphicons-halflings-regular.ttf
│ ├── glyphicons-halflings-regular.woff
│ └── glyphicons-halflings-regular.woff2
├── img
│ ├── favicon.ico
│ └── grid.png
├── index.html
├── js
│ ├── base.js
│ ├── bootstrap.min.js
│ └── jquery-1.10.2.min.js
├── search
│ ├── lunr.js
│ ├── main.js
│ ├── search_index.json
│ └── worker.js
├── sitemap.xml
└── sitemap.xml.gz
7 directories, 28 files
確認
ブラウザでindex.htmlを確認すると、正常に表示されていますね♪
とても簡単です！
終わりに
今回はインストールからシンプルなHTML出力までの確認をしました。
MkDocsの本領発揮はカスタマイズ性の高さなので、次回はその辺を試してみようと思います♪
皆さんも脱Office/GoogleDocsを目指してみてはいかがでしょうか♪