python製のMkDocsを使ってMarkdownでドキュメントを作成する

Markdownで記述した内容を静的サイトとして生成してくれるMkDocsを利用するまでの手順を記述してます。使い方もとてもシンプルで非常に便利です。

pipを使ってインストールします。

pip install mkdocs

バージョンを確認してみます。

mkdocs -V

<出力結果>
mkdocs, version 1.1.2 from c:\users\usertest\scoop\apps\python\3.8.4\lib\site-packages\mkdocs (Python 3.8)

プロジェクトを作成してみます。

mkdocs new test-mkdocs

MkDocsを起動みます。

cd test-mkdocs
mkdocs serve

ブラウザから http://localhost:8000にアクセスすると以下の画面が表示されます。

TOPページを編集してみます。「docs」フォルダ配下にある「index.md」を編集すると、TOPページに反映されます。

ホットリロードなので、編集がすぐに反映されます。

次にページを追加します。「docs」フォルダ配下に「test.md」という名前で以下の内容で追加します。

## コードを表示
- コードを表示します

```
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

ブラウザから http://localhost:8000/test にアクセスするとページが追加されていることが確認できます。

ページを設定する場合は、プロジェクト配下にある「mkdocs.yml」を以下のように編集します。

site_name: My Docs
pages:
  - Page1: index.md
  - Page2: test2.md
  - Page3: test.md

buildコマンドを実行すると静的ファイルが「site」フォルダ内に生成されます。

mkdocs build