マークダウンで書いたドキュメントを簡単に管理・閲覧できるよういしたいと思い、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"]
ビルドします。
$ 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
以下のようにファイルが作成されます。
$ tree workspace/
workspace/
└── doc
├── docs
│ └── index.md
└── mkdocs.yml
コンテナの起動
ドキュメント作成済みであれば、以下のようにしてコンテナを起動します。
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 のページが表示されます。
GitLab Pages で公開する
ローカルでの環境は以上で整ったので、次は GitLab に push したら MkDocs のビルドを行って GitLab Pages に公開するように設定します。
作成した .gitlab-ci.yml は以下です。
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 に公開しています。
