MkDocsを初めて触ってみた

はじめに

  • markdownで複数ページからなるドキュメントを作る方法を探していた。
  • mdbookを使い始めたが、調べたら他にも色々なツールがあるとのこと。
  • その中で今回はMkDocsを使ってみた

MkDocsとは

  • 静的サイトジェネレータ
  • 文章はmarkdownファイル
  • buildすることでhtmlファイルを作ることができる
  • テーマ（ページデザイン）にはテンプレートがあり、簡単にキレイなページを作れる
  • Python製

環境

OS: Windows 10

導入手順

pip install mkdocs

新しくドキュメントを作る

mkdocs test [フォルダ名]
mkdocs test mkdocs_test

実行するとコマンドプロンプトには以下のようなテキストが出力されます。

INFO     -  Creating project directory: mkdocs_test
INFO     -  Writing config file: mkdocs_test\mkdocs.yml
INFO     -  Writing initial docs: mkdocs_test\docs\index.md

mkdocs newで作ったフォルダは最初は以下のような構成になっています。

mkdocs_test
├ docs
│  └ index.md
└ mkdocs.yml

カレントディレクトリを、新しく作ったフォルダに移動してから

mkdocs serve

実行するとコマンドプロンプトには以下のようなテキストが出力されます。

INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.11 seconds
INFO     -  [08:40:04] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [08:40:04] Serving on http://127.0.0.1:8000/

http://127.0.0.1:8000/にアクセスしてページを見てみましょう

無事表示ができたようです。

ページを作ってみる

docsフォルダ内にpage_1.mdを作り、中身は以下のようにします。

# Hello World

Hello World

これでmkdocs buildを行ってみると、フォルダ構成は以下のように変わります。

(ドキュメントのフォルダ)
├ docs
│  ├ index.md
│  └ page_1.md
├ site
│  ├ ...(省略)
│  └ page_1        <- 新しくフォルダが作成されている
│     └ index.html <- 新しくhtmlが作成されている
└ mkdocs.yml

さて、mkdocs serveからhttp://127.0.0.1:8000/にアクセスしてみると次のようになってます。 （画像は右上のハンバーガーボタンを押して上の部分を表示させた後のものになります）

Hello Worldを押してみると、先程つくったページが表示されました

おわりに

  • MkDocsを使って簡単なドキュメントを作ってみました。