MkDocsのライブエディタをDockerで構築してみた

はじめに

データアナリティクス事業本部の藤川です。
仕様書や手順書など、社内で利用するドキュメントはオンラインストレージサービスやGitで共有されていると思います。
では、API仕様書のように外部に公開したいドキュメントはどのように作成されているでしょうか。
SphinxでしょうかMkDocsでしょうか、弊社内でも派閥が二分するようです。

私のプロジェクトでは、Markdownとの親和性を最優先にMkDocsを採用することに決めました。
そして、この度、めでたくMkDocsのライブエディタを構築できましたので、Dockerコンテナでの構築方法をご紹介したいと思います。

構築方法

３パターンご用意しました。お好きな方法を選んでください。

コンテナイメージを使用する場合

• こちらにDockerのコンテナイメージをご用意しました。docker pullし、2回目以降/通常利用時はここからに進んでください。

  docker pull ghcr.io/cm-fujikawa/mkdocs:latest

リポジトリを利用する場合

• こちらにソースコードをご用意しました。git cloneし、2回目以降/通常利用時はここからに進んでください。

  git clone https://github.com/cm-fujikawa/mkdocs.git

一から構築する場合

• MkDocs初期設定に進んでください。

MkDocs初期設定

初回のみ/リポジトリに作成済み

1. documentフォルダを作成し、必要なフォルダ構成（docs、site）を作ります。

   mkdir document && cd document
   mkdir docs
   mkdir site

2. mkdocs.ymlファイルを作成します。

   vi mkdocs.yml

3. リポジトリに保存する場合は、.gitignoreファイルを作成します。

   vi .gitignore

4. siteフォルダをリポジトリに登録しないよう設定します。

   site/

コンテナ構築方法

初回のみ/リポジトリに作成済み

1. Dockerfileを作成します。

   vi Dockerfile

• Dockerfile

  FROM alpine
  
  WORKDIR /document
  RUN apk update && \
      apk add --no-cache python3 py3-pip && \
      pip3 install --upgrade pip && \
      pip3 install mkdocs mkdocs-material fontawesome_markdown
  
  EXPOSE 8000
  CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]

利用方法

初回のみ

1. コンテナイメージを作成します。

   docker build . -t ghcr.io/cm-fujikawa/mkdocs:latest

2回目以降/通常利用時はここから

1. コンテナを起動します。

   docker run --rm --name mkdocs \
       -d -p 8000:8000 -v ${PWD}/document:/document ghcr.io/cm-fujikawa/mkdocs:latest

2. http://localhost:8000にアクセスすると、MkDocsが表示されます。（Markdownファイルがないため、本文は404エラーとなっています）

ドキュメントの編集・確認方法

1. docsフォルダにあるmkdocs.ymlファイル、documentフォルダ配下のMarkdownファイルを編集してください。
2. リアルタイムに、編集内容がブラウザ表示に反映されます。
3. こちらにあるmkdocs.ymlファイルで試してみました。
4. そのままでは、エラーとなるため、次の行をコメントアウトするか、Dockerfileファイルにfontawesome_markdownを加えて、pip3 install mkdocs mkdocs-material fontawesome_markdownのように編集して、コンテナを再構築してください。

   - fontawesome_markdown

5. 当然ですが、同じ結果が得られました。（Markdownファイルがないため、本文は404エラーとなっています）

作業終了時

1. コンテナを停止します。--rmオプションを指定しているので、コンテナは削除されます。

   docker stop mkdocs

さいごに

MkDocsは、YAML形式の設定ファイルとMarkdown形式のドキュメントからリッチなデザインの仕様書を簡単に出力できます。
テキストファイルですので、Gitリポジトリで版管理できます。いつ、誰がどのような理由で更新したのか履歴を残せますし、デグレや誤った文書を公開してしまうリスクを軽減できるでしょう。

今回ご紹介したライブエディタも、MkDocsの設定ファイルに合わせて、プラグインを追加し、リポジトリで配信できるのでメンテナンスの手間も軽減できます。
簡単に構築できて、良いこと尽くめなので、皆様のプロジェクトでも是非導入をご検討ください。

あわせて読みたい