Markdownで記載したコンテンツをGitHub Actionsの(Pagesなどでは無く)Self-Hosted Runnerを使ってMkDocsでビルドし、NginxでWebサイトとして公開する手順をメモしておきます。MkDocs自体はsig9/mkdocs-materialというDockerコンテナを使ってビルドします。
尚、今回はSelf-Hosted Runner側にはx64のUbuntuを利用します。
MkDocsでコンテンツを開発する際、mkdocs serveを実行することでライブサーバを起動できます。このライブサーバはデフォルトで「localhost:8000」をListenします。今回はMkDocsがListenするアドレス・ポートを変更する方法をメモしておきます。
新たにMkDocs環境を作成したところ、mkdocs serveしてもコンテンツ変更時にライブリロードされず、「mkdocsを停止・再開」が必要になってしまいました‥ この問題は以下のIssueで報告されていました。
以前にMkDocsで自動的に見出しへ連番を割り当てるというメモを書きました。これ以外にもMkDocsにmkdocs-enumerate-headings-pluginを追加すると見出しに連番を割り当てることができます。しかも同じページ内だけではなく、異なるページも加味した上で連番を割り当てることができます。GitHubのFeaturesには以下の記載があります。
- Automatically number all headings and (optionally) give each page an sequential chapter number
- Great for writing (technical) reports
- Compatible with plugins like awesome-pages and monorepo
- Compatible with markdown_extensions like pymdownx.snippets
- Compatible with themes like mkdocs-material
- Easy to customize styling through CSS
今回はこのプラグインを実際に試してみます。
MkDocsには見出しに対して自動的に連番を割り当てるmkdocs-add-number-pluginというプラグインがあるそうです。今回は実際にこのプラグインを試してみました。
Mermaid を使うとテキストを記載するだけで作図を行うことが出来ます。 MkDocs 上でも Material for MkDocs の Diagrams を使うことで Mermaid を利用した作図を行うことが出来ます。 今回は MkDocs 上で Mermaid を利用して作図する方法をメモしておきます。
MkDocs のバージョン 1.5.3 をインストールした Docker コンテナを作成しました。 DockerHub の以下 URL に登録してあります。
MkDocs ではコードをハイライトして表示することが出来ます。 また、コードハイライトを行う際に行番号を表示することが出来ます。 今回は「普段は行番号を表示しつつ、特定のコードブロックのみ、行番号を表示しない」方法をメモしておきます。
MkDocs でサポートされる記法のうち、幾つかをメモしておきます。 機能によっては事前に mkdocs.yml で有効化しておく必要があります。
静的サイトジェネレーターである MkDocs に関して、日本語の情報源としては Mebiusbox さんがお書きになっている MkDocsによるドキュメント作成 が最強なのでは無いかと思います。 余談ですが 「動かして学ぶ！Rust入門」の執筆 によると Mebiusbox さんは さんは 動かして学ぶ！Rust入門 の著者でもあるそうです (すごい)。
以前に HBFM (Markdown 拡張) を追加した MkDocs の Docker イメージ というメモを書きました。 このは ハートビーツ さんが作成されたプラグインを取り込んだ MkDocs の Docker イメージを利用する前提になっています。 今回は Docker コンテナは利用せず、ローカルに MkDocs をインストールする手順をメモしておきます。