MkDocs + GitLab Pages でドキュメント管理

マークダウンで書いたドキュメントを簡単に管理・閲覧できるよういしたいと思い、MkDocs と GitLab Pages を使ってみました。 ## 概要 Markdown で書いたドキュメントを MkDocs を使って静的サイトに変換します。 MkDocs のビルドは GitLab CI/CD を使って自動で行い、出力された静的サイトを GitLab Pages で公開します。 また、ローカル環境での確認用に、Docker を使って MkDocs が動作する環境を作成します。 GitLab-Runner の設定は済んでいる前提です。 ## ローカル環境の構築 ひとまず GitLab は置いておき、まずはローカル環境で MkDocs が動くようにしてみます。 作成した Dockerfile は以下です。 ``` FROM python:3.9-slim RUN pip install \ mkdocs \ mkdocs-material \ pygments CMD ["mkdocs", "serve", "-a", "0.0.0.0:8000"] ``` ビルドします。 ```shell $ docker build -t mkdocs . ``` ### ドキュメントの新規作成（初回のみ） ドキュメントを何も作成していない状態でコンテナを起動するとエラーとなります。 まずはコンテナ起動時に `mkdocs new doc` を実行してドキュメントを新規作成しました。 ``` docker run -it --rm \ -u "$(id -u $USER):$(id -g $USER)" \ -v $(pwd)/workspace:/workspace \ --workdir="/workspace" \ mkdocs mkdocs new doc ``` 以下のようにファイルが作成されます。 ```shell $ tree workspace/ workspace/ └── doc ├── docs │   └── index.md └── mkdocs.yml ``` ### コンテナの起動 ドキュメント作成済みであれば、以下のようにしてコンテナを起動します。 ```sh docker run -it --rm \ -u "$(id -u $USER):$(id -g $USER)" \ -v $(pwd)/workspace:/workspace \ -p 8000:8000 \ --workdir="/workspace/doc" \ mkdocs ``` ブラウザで http://localhost:8000 にアクセスすれば MkDocs のページが表示されます。 <div class="separator" style="clear: both;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgX00vfMHi3bl-Uhy7X4eLaqYLo7TL1wVXlXNEymPZm9wQXaORmG5WcEqktO1p8Gmi0dUDvkkfwSHOotauiBTX4OfN3BD32NixfUREJTsAqshD75kAL8jV3MaD6ypfl70BUBslg_CUBjWdpWY6XAsy1gLInl3DLQcB0znRWxFkZi9G6PWTJUICygheA/s1217/mkdocs.png" style="display: block; padding: 1em 0; text-align: center; "><img alt="" border="0" width="320" data-original-height="625" data-original-width="1217" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgX00vfMHi3bl-Uhy7X4eLaqYLo7TL1wVXlXNEymPZm9wQXaORmG5WcEqktO1p8Gmi0dUDvkkfwSHOotauiBTX4OfN3BD32NixfUREJTsAqshD75kAL8jV3MaD6ypfl70BUBslg_CUBjWdpWY6XAsy1gLInl3DLQcB0znRWxFkZi9G6PWTJUICygheA/s320/mkdocs.png"/></a></div> ## GitLab Pages で公開する ローカルでの環境は以上で整ったので、次は GitLab に push したら MkDocs のビルドを行って GitLab Pages に公開するように設定します。 作成した `.gitlab-ci.yml` は以下です。 ```yaml image: python:3.9-slim before_script: - pip install --upgrade pip - pip install mkdocs - pip install mkdocs-material - pip install pygments pages: stage: build script: - cd workspace/doc - mkdocs build - mv site ../../public artifacts: paths: - public only: - main ``` 特に難しいところはないかと思います。 `mkdocs build` でビルドすると `site` に出力されるので、`public` にリネームして GitLab Pages に公開しています。 ## 参考 URL - https://qiita.com/hykisk/items/ebff2f7cd2e8100a6bbe - https://kurotorimkdocs.gitlab.io/kurotorimemo/040-Documents/MkDocs/mkdocsGitLab/