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

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

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

環境

  • OS windows10 pro 64bit
  • python 3.6.8
  • pip 20.1.1

MkDocsインストール

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

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

MkDocsプロジェクト作成

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

MkDocsを起動みます。

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

MkDocs使い方

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

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

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

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

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

HTML生成

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