MkDocs の設定いろいろ

Fri, 03 Jun 2022 00:00:00 +0900

MkDocs の細かい設定いろいろです。

必要に応じて適宜更新していきたいと思います。

URL を自動でハイパーリンクする

以下の拡張機能を有効にします。

markdown_extensions:
 - pymdownx.magiclink

Material for MkDocsで打ち消し線が動作するようにする

以下の拡張機能を有効にします。

markdown_extensions:
 - pymdownx.tilde

スペース2個でリストがインデントされるようにする

デフォルトではスペース4個でないとリストがインデントされません。
これをスペース2個でもインデントされるようにするには、mdx_truly_sane_lists という拡張機能をインストールします。

$ pip install mdx_truly_sane_lists

mkdocs.yml に以下を追記します。

markdown_extensions:
 - mdx_truly_sane_lists:
 nested_indent: 2

更新日時を表示する

$ pip install mkdocs-git-revision-date-localized-plugin

plugins:
 - search
 - git-revision-date-localized

Material for MkDocs を使っている場合はこれだけで全ページの下部に更新日時が表示されるようになります。
オプション設定で書式などを変更することもできるようです。

https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/options/

参考 URL

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

Mon, 23 May 2022 00:00:00 +0900

マークダウンで書いたドキュメントを簡単に管理・閲覧できるようにしたいと思い、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 に公開しています。

Mkdocs on ポンコツ地方エンジニアの技術ブログ

MkDocs の設定いろいろ

URL を自動でハイパーリンクする

Material for MkDocsで打ち消し線が動作するようにする

スペース2個でリストがインデントされるようにする

更新日時を表示する

参考 URL

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

概要

ローカル環境の構築

ドキュメントの新規作成（初回のみ）

コンテナの起動

GitLab Pages で公開する

参考 URL