コンテンツにスキップ

MkDocs

  • in MkDocs, Zensical
  • このページは約9分で読めます

「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
  • このページは約6分で読めます

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分で読めます

MkDocsがListenするアドレス・ポートを指定する

MkDocsでコンテンツを開発する際、mkdocs serveを実行することでライブサーバを起動できます。このライブサーバはデフォルトで「localhost:8000」をListenします。今回はMkDocsがListenするアドレス・ポートを変更する方法をメモしておきます。

  • in MkDocs
  • このページは約1分で読めます

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

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

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

  • in MkDocs
  • このページは約2分で読めます

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

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

  • in MkDocs
  • このページは約1分で読めます

MkDocs のコードハイライトでブロック毎に行番号表示する・しないを制御する

MkDocs ではコードをハイライトして表示することが出来ます。 また、コードハイライトを行う際に行番号を表示することが出来ます。 今回は「普段は行番号を表示しつつ、特定のコードブロックのみ、行番号を表示しない」方法をメモしておきます。

  • in MkDocs
  • このページは約5分で読めます

MkDocs でサポートされる記法

MkDocs でサポートされる記法のうち、幾つかをメモしておきます。 機能によっては事前に mkdocs.yml で有効化しておく必要があります。