Skip to content

MkDocs

「MkDocs + Material for MkDocs」の後継は「Zensical」

Material for MkDocsのバージョン9.7.0のリリースノートには以下の記載があります。

This is the last release of Material for MkDocs that will receive new features. Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs for 12 months at least.

Deepl翻訳

Material for MkDocsの新機能提供は、これが最後のリリースとなります。今後、Material for MkDocsチームは、第一原理に基づいて構築された次世代静的サイトジェネレータであるZensicalに注力します。Material for MkDocsについては、少なくとも12か月間は重大なバグ修正とセキュリティ更新を提供します。

従来は「MkDocsにMaterial for MkDocsテーマをインストールして利用する」という構成でしたが、後継にあたるZensicalは単体で「MkDocsとMaterial for MkDocsテーマ」の機能をカバーするようです。

コマンドでの操作感は「ZensicalとMkDocsで全く同じ」である為、操作にこまることは無いと思いますが、Zensicalの基本的な利用方法をメモしておきます。

  • in MkDocs
  • 7 min read

GitHub ActionsからDockerでMkDocsビルドを実行し、Nginxでサイトを公開する

Markdownで記載したコンテンツをGitHub Actionsの(Pagesなどでは無く)Self-Hosted Runnerを使ってMkDocsでビルドし、NginxでWebサイトとして公開する手順をメモしておきます。MkDocs自体はsig9/mkdocs-materialというDockerコンテナを使ってビルドします。

尚、今回はSelf-Hosted Runner側にはx64のUbuntuを利用します。

  • in MkDocs
  • 1 min read

MkDocsでClick 8.2.1「より新しいバージョン」を使うとライブリロードされない

新たにMkDocs環境を作成したところ、mkdocs serveしてもコンテンツ変更時にライブリロードされず、「mkdocsを停止・再開」が必要になってしまいました‥ この問題は以下のIssueで報告されていました。

clickのリリース履歴によると8.2.2は廃止されており、現時点の最新バージョンは8.3.0のようです。

  • in MkDocs
  • 2 min read

MkDocsでページを跨って連番を割り当てる

以前に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

今回はこのプラグインを実際に試してみます。