エンジニアの大石です。

以前にMarkdownのドキュメント作成についてコラムを書いたことがありましたが、

今回はMarkdownで書いたドキュメントだけでウェブサイトが作れるMkDocsというツールについて紹介したいと思います。

MkDocsとは

MkDocsとは、Pythonで作られた静的サイトジェネレーターの一種で、

Markdown形式で記述されたドキュメント（mdファイル）をHTMLページに変換し簡単にウェブサイトを作成できるツールです。

テーマやプラグインなどの拡張機能をサポートしており、カスタマイズ性の高さが特徴です。

導入手順

Pythonをインストールしている方は、pipコマンドで導入するのが手っ取り早いでしょう。

私の場合はDockerで作業したかったのでDockerを使って導入しました。

以下にその手順を書いていきます。

筆者の環境

• Windows10
• Docker Desktop (WSL2バックエンドで動作)
• Ubuntu 20.04 LTS

1.作業用フォルダとファイルを作成します

DocumentRoot
├── docs/
│   └── index.md/
└── mkdocs.yml

• DocumentRoot:作業用フォルダ（名前はなんでも）
• docs:mdファイルを入れるフォルダ（名前はなんでも）
• index.md:ドキュメントファイル、ページごとに作成する
• mkdocs.yml:設定ファイル

2.mkdocsに設定を記述します

site_name: サイト名
docs_dir: 'docs'

• site_name:付けたい名前
• docs_dir:mdファイルが入っているフォルダ名

3.DockerHubで配布されているイメージを取得します

参照:https://hub.docker.com/r/squidfunk/mkdocs-material

以下のコマンドを実行します

docker pull squidfunk/mkdocs-material

4.コンテナを起動します

以下のコマンドを実行します

ポートは適宜変更してください

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

公開する方法

以下のコマンドを実行します

mkdocs build

siteフォルダとその中にHTML、CSS、Javascriptが自動生成されるので公開用のサーバーにアップロードします。

GitHubと連携すれば、自前のサーバーを用意しなくてもGitHub Pagesというウェブホスティングサービスを使ってネット上に公開することも出来ます。

Webアプリのマニュアルページを作ってみた

実際にMkDocsを使ってWebアプリのマニュアルページを作ってみました。（マニュアル）

本来の用途とは若干違うかもしれませんが、こういったサイトを即席で作りたい場合に役立ちます！

使っていて便利に感じた点

• mkdocs.ymlファイルに設定を記述するだけなのでセットアップが簡単
• ホットリロードが効いているので、変更が即時サイトに反映されて確認できるので作業効率が上がる
• テーマを選ぶだけでサイトのデザインを変更できる
• プラグインが簡単に追加できるので、開発する手間がかからない
  • HTML、CSS、Javascriptを触らなくていい
    • カスタマイズしたい場合は独自にCSS、JSを追加することもできる
    • Markdownの記法さえ守れば自動的にレイアウトを統一してくれる
      • ドキュメントを書く作業に集中できる
  • ナビゲーションを設置できる
  • 見出しから目次を自動生成してくれる
  • サイト内検索機能が使える
  • 絵文字やアイコン、アラートの装飾が使える
• ドキュメントはテキストベースなのでGitで管理可能
  • いつ、誰が、どこを変更したか履歴が確認できる
  • シンプルなmdファイルとmkdocs.ymlのみ管理すればOK
  • HTMLなどはmdファイルを元に自動生成されるので、Gitの管理下に置く必要がない
    • （独自に追加したCSS、JSがある場合は別）