[[📒Articles]] > [[📒2025 Articles]] ![[2025-02-23.webp|cover-picture]] [[Obsidian]]や[[obsidian.nvim]]で快適に管理でき、クローズドにデプロイ可能なドキュメントサイト... しかも無料で仕事にも使える。[[MkDocs]]でそんなドキュメントベースを実現してみました。 本記事は以下のような読者を想定しています。 - [[Python]]、[[Markdown]]、[[YAML]]、ターミナル操作の基礎知識がある - [[Obsidian]] または [[obsidian.nvim]] について知識や利用経験がある - [[ドキュメンテーションビルダー]]が何かを知っている > [!hint] 最終成果物だけが欲しい方へ > [[#一発で環境構築するシェル]] をご覧ください。 # はじめに 2025年2月20日、[[Obsidian]]界隈を揺るがすビッグニュースが舞い込んできました。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://obsidian.md/favicon.svg" /> <span class="link-card-v2-site-name">obsidian.md</span> </div> <div class="link-card-v2-title"> Obsidian is now free for work </div> <div class="link-card-v2-content"> Starting today, the Obsidian Commercial license is optional. Anyone can use Obsidian for work, for free. Explore ... </div> <img class="link-card-v2-image" src="https://obsidian.md/images/blog/free-for-work.png" /> <a href="https://obsidian.md/blog/free-for-work/"></a> </div> それまで有償ライセンスの購入が必須だった[[Obsidian]]の商用利用が、なんとライセンスなしで使えるようになったのです。(別途、寄付は受け付けています) 私は2021年から[[Obsidian]]を利用しており、管理している[[Vault]]は[[Obsidian Publish]]で公開しています。何を隠そう本サイト [[Minerva]] がそれにあたります。4年が経った今でも[[PKM]]や[[Minerva]]の管理は継続しており、先日[[ノート]]の数が10000を超えました。 しかし、仕事では商用ライセンスなしに[[Obsidian]]を利用できません。申請は出したものの、結局それが通ることはなく、1年前に諦めて[[obsidian.nvim]]を使ってローカルドキュメント管理を今日まで行ってきました。 それが、先ほどのビッグニュースにより状況は変わりました。今後は[[Obsidian]]を業務で利用できるようになり、それを前提としたよりエレガントな[[ドキュメンテーション]]運用が求められていくと思っています。昨今は[[AI]]ブームということもあり、プレインテキストファイルの[[Markdown]]管理という形態も重宝されることでしょう。 ## MkDocs 私がよく使う[[Markdown]]ベースの[[ドキュメンテーションビルダー]]は[[MkDocs]]です。[[Material for MkDocs]]とセットで使っています。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://squidfunk.github.io/mkdocs-material/assets/favicon.png" /> <span class="link-card-v2-site-name">squidfunk.github.io</span> </div> <div class="link-card-v2-title"> Material for MkDocs </div> <div class="link-card-v2-content"> Write your documentation in Markdown and create a professional static site in minutes – searchable, customizable ... </div> <img class="link-card-v2-image" src="https://squidfunk.github.io/mkdocs-material/assets/images/social/index.png" /> <a href="https://squidfunk.github.io/mkdocs-material/"></a> </div> 2017年頃に[[Minerva]]の前身を管理するために利用し始めてから8年...、他の[[ドキュメンテーションビルダー]]も定期的に調査しているものの、公私共に[[MkDocs]] + [[Material for MkDocs]]の利用が続いています。[[OSS]]のドキュメントとして管理しているドキュメントは以下2つです。 - [Various Complements](https://tadashi-aikawa.github.io/docs-obsidian-various-complements-plugin/) - [Jumeaux](https://tadashi-aikawa.github.io/jumeaux/) 前者 [[🦉Various Complements]] のドキュメントについて、実は[[Obsidian]]で書いています。[[MkDocs Roamlinks Plugin]]というプラグインを自分でforkして使い、[[wikiリンク]]に対応していました。 本記事でも同様の構成について紹介しますが、[[MkDocs Roamlinks Plugin]]は使わない別のアプローチをとります。次のセクションからプロジェクトの構築と、有効にするプラグインを1つずつ紹介していきましょう。 ## 環境 本記事で利用する環境と、インストールしたライブラリのバージョンは以下の通りです。 | 対象 | バージョン | | --------------------------------------------- | ------------------------ | | [[Ubuntu]] | 24.04.1 LTS | | [[Python]] | 3.13.1 | | [[Pip]] | 24.3.1 | | [[MkDocs]] | 1.6.1 | | [[Material for MkDocs]] | 9.6.5 | | [[Awesome Nav for MkDocs]] | 3.0.0 | | [[mkdocs-git-authors-plugin]] | 0.9.2 | | [[mkdocs-git-revision-date-localized-plugin]] | 1.3.0 | | [[MkDocs Backlinks Section Plugin]] | 0.0.4 | | [[mkdocs-obsidian-bridge]] | 1.2.0 (fork版は `84cc938`) | | [[MkDocs GLightbox]] | 0.4.0 | ### [[mkdocs-obsidian-bridge]]のfork版 一部の内容は[[mkdocs-obsidian-bridge]]のfork版を使っています。インストールコマンドの例です。 ```console pip install git+https://github.com/tadashi-aikawa/mkdocs-obsidian-bridge ``` fork版の差分は [[mkdocs-obsidian-bridge#fork版について]] をご覧ください。 # プロジェクトの作成 まずは最小限のドキュメンテーションプロジェクトを作成しましょう。 ## Pythonの準備 [[Python]] 3.13をインストールしておいてください。[[mise]]だと以下のコマンドを実行します。 ```console mise use -g [email protected] ``` ## ディレクトリ作成 必要なディレクトリを作成します。ルートディレクトリは `mkdocs-sample` とします。 ```console mkdir mkdocs-sample cd $_ mkdir docs ``` ## 仮想環境の準備 `.venv` ディレクトリに[[仮想環境を作成 (Python)|仮想環境を作成]]します。 ```console python -m venv .venv ``` 作成した[[仮想環境を有効 (venv)|仮想環境を有効]]にします。 ```console source .venv/bin/activate ``` ## MkDocsとMaterial for MkDocsのインストール [[MkDocs]]と[[Material for MkDocs]]をインストールします。 ```console pip install mkdocs mkdocs-material ``` ## 設定ファイルの作成 最低限の設定ファイルを作成しましょう。 `mkdocs.yml` ```yaml site_name: MkDocs Sample theme: name: material ``` ## トップページの作成 トップページとして `index.md` を `docs` フォルダに作成します。 `docs/index.md` ```markdown Hello MkDocs!! ``` ## 動作確認 [[MkDocs]]のコマンドを実行します。 ```console mkdocs serve ``` `http://localhost:8000` にアクセスしてページが表示されればOKです。 ![[Pasted image 20250222204825.png|frame]] # 必ず入れておきたい機能 [[Obsidian]]との互換性もあり、利用頻度の高い設定を最初にしましょう。 ## ウィキリンク まずは[[wikiリンク]]を使えるようにします。[[MkDocs]]や[[Material for MkDocs]]にその機能はないため、[[mkdocs-obsidian-bridge]]を使います。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://github.githubassets.com/favicons/favicon.svg" /> <span class="link-card-v2-site-name">GitHub</span> </div> <div class="link-card-v2-title"> GitHub - GooRoo/mkdocs-obsidian-bridge: Use Obsidian’s syntax for your website with this MkDocs plugin </div> <div class="link-card-v2-content"> Use Obsidian’s syntax for your website with this MkDocs plugin - GooRoo/mkdocs-obsidian-bridge </div> <img class="link-card-v2-image" src="https://opengraph.githubassets.com/ab138e0b241f897112c1e1413cbc80c0b420c3e9cdc7716c78be9d71ccfa1f8e/GooRoo/mkdocs-obsidian-bridge" /> <a href="https://github.com/GooRoo/mkdocs-obsidian-bridge?tab=readme-ov-file"></a> </div> ### マークダウンファイルに追加する [[mkdocs-obsidian-bridge]]は[[Obsidian]]の[[Vault]]形式で書かれた[[Markdown]]などのファイルを、[[MkDocs]]の形式に変換してくれる[[MkDocs]]のプラグインです。その動作確認用に[[Markdown]]ファイルを2つ用意します。 `docs/MkDocs.md` ```markdown Python製のSSG。Sphinxとは異なり、フォーマットにはMarkdownを使う。 > [MkDocs](https://www.mkdocs.org/) ``` `docs/Material for MkDocs.md` ```markdown [[MkDocs]]でMaterial Designに沿ったドキュメントを作成するためのフレームワーク。 > [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) ``` `Material for MkDocs.md` の中に `MkDocs.md` への[[wikiリンク]]があることがポイントです。この時点では[[wikiリンク]]が認識されていないことを確認しておきましょう。 ![[Pasted image 20250222205850.png|frame]] *`[[MkDocs]]` はそのまま表示される* ### mkdocs-obsidian-bridgeのインストール [[Pip]]でインストールします。 ```console pip install mkdocs-obsidian-bridge ``` ### 設定の変更 `mkdocs.yml` の `plugins` にインストールしたプラグインの設定を追加します。 ```yaml plugins: - obsidian-bridge ``` ### 動作確認 再度 `Material for MkDocs` にアクセスし、`MkDocs.md` への[[wikiリンク]]が有効になっていることを確認します。 ![[Pasted image 20250222210322.png|frame]] *`[[MkDocs]]` がリンクとして表示されている* > [!info] > `MkDocs.md` は `Material for MkDocs.md` と同じディレクトリに配置されていなくても[[wikiリンク]]は正しくリンク先を設定します。ただし、複数の候補がある場合はその限りではありません。その場合は一意に特定できるprefixの指定が必要です。 > [!hint] ビルド時に表示されるWARNINGについて > `mkdocs serve` コマンド実行後のビルドログに `WARNING - [ObsidianBridgePlugin] Unable to find MkDocs in directory .../mkdocs-sample/docs` のような警告が表示されます。これは #2025/02/22 時点での [[mkdocs-obsidian-bridge]] では非表示にできません。 > > これらのWARNINGを消したい場合は [[#mkdocs-obsidian-bridge のfork版]] を使ってください。 ## Callout [[Obsidian]]の[[コールアウト]]を使えるようにします。 ### マークダウンファイルに追加する [[wikiリンク]]のときと同様に、まずは機能していない状態を確認します。新しく `サポートする記法.md` を作成しましょう。 `サポートする記法.md` ````markdown ## 概要 本プロジェクトでサポートする特殊な記法を紹介します。 ## ウィキリンク - [[MkDocs]] ## Callout > [!info] > INFOのCallout ```` ![[Pasted image 20250222215446.png|frame]] *Calloutの記法はただの引用ブロックになっている* ### 設定変更 先ほどインストールした[[mkdocs-obsidian-bridge]]の設定で有効にするだけです。 ```yaml markdown_extensions: - obsidian_callouts ``` ### 動作確認 [[コールアウト]]が有効なっていることを確認できればOKです。 ![[Pasted image 20250222215513.png|frame]] ## コードのシンタックスハイライト コードのハイライトがどこでも効くように設定します。 ### マークダウンファイルに追加する いつものように設定前の状態を確認します。 > [!attention] > 以後は `サポート記法.md` に追加する項目のみを記載します。 ~~~markdown ## ネストしたコードブロック > [!hint] > > ```typescript > const a = 1 > const b = 1 > ``` ~~~ ![[Pasted image 20250222215640.png|frame]] *表示が崩れてしまい、ハイライトもされない* ### 設定変更 [[SuperFences (PyMdown Extensions)|SuperFences]]の設定を追加します。 ```yaml markdown_extensions: - pymdownx.superfences ``` ### 動作確認 ![[Pasted image 20250222220708.png|frame]] ## 検索 サイトに必須とも言える検索機能を追加します。 ### 設定前 ![[Pasted image 20250223104204.png|frame]] *右上に検索バーがない* ### 設定変更 ```yaml plugins: - search: lang: ja ``` > [!caution] > `lang: ja` を指定しないと **本文中の日本語ワード** が検索結果にヒットしません。指定しなくても見出しに含まれる日本語ワードはヒットします。 > [!info] > `mkdocs.yml` で `plugins` プロパティを指定していない場合は、`search` を追加しなくてもデフォルトで検索機能は有効になります。 ### 動作確認 ![[Pasted image 20250223104424.png|frame]] *検索欄が追加される* ## サイドナビゲーションのカスタマイズ 左サイドに表示されるナビゲーションの内容はファイル/ディレクトリの構成と中身によって決まります。一見楽に見えますが、以下の問題がすぐに発生するため、内容をカスタマイズできるようにします。 - 表示順が制御できない - 表示内容が制御できない - ディレクトリ構造に依存してしまう > [!info] > [[📓Minervaのディレクトリ構成]]では、基本的に[[Markdown]]ファイルを `Notes` 配下にフラットに配置しています。 ### 設定前 ![[Pasted image 20250223130133.png|frame]] *内容はフラットでアルファベット順* ### Awesome Nav for MkDocsのインストール `mkdocs.yml` には全体的な設定を記載したいので、ナビゲーションに表示する情報は別ファイルで管理します。[[Awesome Nav for MkDocs]]を使って、`nav` の[[YAML]]ファイルを切り離します。 ```console pip install mkdocs-awesome-nav ``` ### 設定変更 ```yaml plugins: - awesome-nav ``` ### ナビゲーションファイルの作成 デフォルトでは `docs/.nav.yml` を参照するので、ファイルを作成します。 `docs/.nav.yml` ```yaml nav: - index.md - Material for MkDocs.md # エイリアス - えむけーどっくす: MkDocs.md # 一度エイリアスが紐づくと以降はすべて同じ表記になる - MkDocs.md # えむけーどっくす - hoge: MkDocs.md # えむけーどっくす # 階層をネスト - ネスト1: - サポートする記法.md - ネスト2: - Material for MkDocs.md ``` > [!caution] > 一度エイリアスを設定すると、**以後は同じ参照先に対して同じ表示名が使われ**続けるという制約が発生します。これは、**同じページがナビゲーションの異なる箇所に2度登場することはない**という前提に基づいている可能性が高いです。(未調査) #### 2025/11/30 追記 [[YAML]]ではなく[[Markdown]]+[[wikiリンク]]形式での記述にも対応できます。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/favicon-64.png" /> <span class="link-card-v2-site-name">Minerva</span> </div> <div class="link-card-v2-title"> 📜2025-11-19 Awesome Nav for MkDocsのナビゲーションをMarkdownかつWikiリンクの箇条書きで表現する </div> <div class="link-card-v2-content">Awesome Nav for MkDocsのナビゲーションをObsidianのMarkdown内部リンク形式で管理した経緯やメリット、YAML変換の自動化手法、Live Reloading時の無限ループ回避策、mkdocs-gen-filesによる仮想的な.nav.yml生成方法などを検証した内容。</div> <img class="link-card-v2-image" src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/Notes/attachments/activity.webp" /> <a data-href="📜2025-11-19 Awesome Nav for MkDocsのナビゲーションをMarkdownかつWikiリンクの箇条書きで表現する" class="internal-link"></a> </div> %%[[📜2025-11-19 Awesome Nav for MkDocsのナビゲーションをMarkdownかつWikiリンクの箇条書きで表現する]]%% ノート間につながりができ、補完やリネーム、[[内部リンク]]や[[バックリンク]]による移動など多くのメリットがあるのでオススメです。 ### 動作確認 ![[Pasted image 20250223165559.png|frame]] *指定通りの階層になる* ## 画像のズーム変更 画像のサイズによってはページの初期表示サイズでは見にくい場合があります。画像をクリックしたら画面いっぱいに表示しつつ、ズーム値も変更できるようにします。 ### Markdownファイルに追加する ```markdown ## 画像  ``` ![[Pasted image 20250226220209.png|frame]] *画像をクリックして拡大したりはできない* ### MkDocs GLightboxのインストール [[MkDocs GLightbox]]プラグインをインストールします。 ```console pip install mkdocs-glightbox ``` ### 設定変更 ```yaml plugins: - glightbox ``` ### 動作確認 ![[Pasted image 20250226220717.png|frame]] *クリックしたら最大化される* ## URLを自動でリンクに変換 [[URL]]を[[Markdown]]形式のリンクで記載するのは一手間です。自動でリンクとして認識されるようにします。 ### マークダウンファイルに追加する ```markdown ## URL https://minerva.mamansoft.net ``` ![[Pasted image 20250223170653.png|frame]] *リンクにならない* ### 設定変更 ```yaml markdown_extensions: - pymdownx.magiclink ``` ### 動作確認 ![[Pasted image 20250223172626.png|frame]] *ハイパーリンクになっていることを確認できる* ## 取り消し線を有効にする デフォルトでは `~~hoge~~` は ~~hoge~~ のような取り消し線になりません。`markdown_extensions` の指定が必要です。 ### 設定変更 ```yaml markdown_extensions: - pymdownx.tilde ``` ## 見出しリンク デフォルトの設定では見出しリンクが表示されません。また、見出しの日本語は認識されないためリンクが壊れます。 ### 設定前 ![[2025-09-27-23-17-08.avif|frame]] *見出しリンクが存在しない* ### 設定変更 ```yaml markdown_extensions: - toc: # 見出しリンクを有効にする permalink: true # 日本語対応 (これがないと日本が無視されるので、Obsidianの見出しリンクが使えない) slugify: !!python/object/apply:pymdownx.slugs.slugify {} ``` > [!attention] > 日本語も含む見出しリンクに対応するには[[#mkdocs-obsidian-bridge のfork版]]が必要です。 > [!info] 日本語対応の詳細について > [[📜2025-09-27 Material for MkDocsをObsidian(mkdocs-obsidian-bridge)で編集する場合でも日本語の見出しを使えるようにする]] をご覧ください。 ### 動作確認 ![[2025-09-27-23-15-38.avif|frame]] *見出しリンクが有効になる* # あったら便利な機能 ここから先の設定は必須とは言えませんが、ドキュメンテーションの運用要件次第では入れておいた方がいいものになります。[[Obsidian]]と互換性のない設定もありますので、その点も考慮が必要です。 ## バックリンクの表示 [[Obsidian Publish]]のように、ページの末尾に[[バックリンク]]が表示されるようにします。 ### 設定前 [[#ウィキリンク]]で作成した以下のファイルで確認します。 `docs/MkDocs.md` ```markdown Python製のSSG。Sphinxとは異なり、フォーマットにはMarkdownを使う。 > [MkDocs](https://www.mkdocs.org/) ``` `docs/Material for MkDocs.md` ```markdown [[MkDocs]]でMaterial Designに沿ったドキュメントを作成するためのフレームワーク。 > [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) ``` `MkDocs` を開きます。 ![[Pasted image 20250223105937.png|frame]] *バックリンクのリストは表示されない* ### MkDocs Backlinks Section Pluginのインストール [[MkDocs Backlinks Section Plugin]]をインストールします。 ```console pip install mkdocs-backlinks-section-plugin ``` ### 設定変更 ```yaml plugins: - backlinks_section: title: "🖇️ Backlinks" # Backlinksセクションの直下に説明を表示しない description: "" # TOCには表示しない add_to_toc: false # バックリンクがなければBacklinksセクションは表示しない hide_if_empty: true ``` ### 動作確認 ![[Pasted image 20250223110843.png|frame]] *MkDocsへリンクしているコンテンツ一覧がBacklinksセクションに表示される* ## 最終更新日の追加 ファイルのコミット履歴は、ファイルそのもののメタデータに比べて信ぴょう性の高い更新日付情報です。[[mkdocs-git-revision-date-localized-plugin]]プラグインを使って、その情報をページ内に埋め込みます。 ### 設定前 前準備として、**[[Git]]リポジトリの初期化とコミット**をしておいてください。ここでは以下のようなコミットをしている前提で進めます。 ```console ● 06917ff (HEAD -> master) second │ 💿Mon Feb 24 19:11:22 2025 +0900 👤<mail_address> │ ● 5eec7b2 Initial commit 💿Sun Feb 23 19:30:09 2025 +0900 👤<mail_address> ``` ![[Pasted image 20250223194124.png|frame]] *ページの下部には更新情報が表示されていない* ### mkdocs-git-revision-date-localized-pluginのインストール ```console pip install mkdocs-git-revision-date-localized-plugin ``` ### 設定変更 ```yaml plugins: - git-revision-date-localized: # コミットされていなくてもINFOに留める strict: false # 作成日も追加する enable_creation_date: true # 日本の表記/時間で locale: ja timezone: Asia/Tokyo ``` > [!warning] > [CIでビルドする場合はクローンの設定変更が必要](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin?tab=readme-ov-file#note-when-using-build-systems-like-github-actions)です。 > [!caution] > [[📝mkdocs-git-revision-date-localized-pluginを入れるとビルドが遅くなる]] 問題があるので対処をした方がいいです。 ### 動作確認 ![[Pasted image 20250224113452.png|frame]] *ページ下部に『最終更新日』と『作成日』が表示された* ## 最終更新者の追加 ### 設定前 [[#最終更新日の追加]]と同様に最終更新者が分かると便利です。[[mkdocs-git-authors-plugin]]プラグインを使って、その情報をページ内に埋め込みます。 ![[Pasted image 20250224113452.png|frame]] *ページ下部に『最終更新者』は表示されていない* ### mkdocs-git-authors-pluginのインストール ```console pip install mkdocs-git-authors-plugin ``` ### 設定変更 ```yaml plugins: - git-authors: # コミットされていなくてもINFOに留める strict: false # メールアドレス(リンク)は不要 show_email_address: false ``` > [!warning] > [CIでビルドする場合はクローンの設定変更が必要](https://github.com/timvink/mkdocs-git-authors-plugin/?tab=readme-ov-file#note-when-using-build-environments)です。 > [!caution] > [[📝mkdocs-git-authors-pluginを入れるとビルドが遅くなる]] 問題があるので対処をした方がいいです。 ### 動作確認 ![[Pasted image 20250224113613.png|frame]] *ページ下部に『最終更新者』が表示された* ## 外部ファイルの埋め込み コードブロックのソースコードなどは、別ファイルに切り出した方が[[LSP]]や[[リンター]]、[[フォーマッター]]などの恩恵が得られて便利なため、埋め込みできるようにします。 > [!caution] > この設定は[[Obsidian]]と互換性がありません。 ### マークダウンファイルに追加する まず埋め込み対象のファイルを作成します。 `sources/sample.ts` ```ts function hello() { console.log("hello"); } ``` それを参照します。 ````markdown ## 外部ファイル埋め込み ```ts title="sample.ts" --8<-- "./sources/sample.ts" ``` ```` ![[Pasted image 20250223113715.png|frame]] *外部ファイルは展開されない* > [!hint] > `--8<--` は ハサミ(`✂`)で切り取るイメージだと思います。 ### 設定変更 ```yaml markdown_extensions: - pymdownx.snippets: check_paths: true base_path: docs ``` > [!info] `check_paths` と `base_path` の設定理由 > [[📝PyMdown ExtensionsのSnippetsで相対パスが指定できない]]問題を解決するためです。 ### 動作確認 ![[Pasted image 20250223123115.png|frame]] ## タブ インストール手順をプラットフォームごとに出し分けるときなどに便利なタブ機能を有効にします。 > [!caution] > この設定は[[Obsidian]]と互換性がありません。 ### マークダウンファイルに追加する ````markdown ## タブ === "npm" ```bash npm install ``` === "pnpm" ```bash pnpm install ``` ```` ![[Pasted image 20250223125037.png|frame]] *タブ表示にはならない* ### 設定変更 ```yaml markdown_extensions: - pymdownx.tabbed: alternate_style: true ``` ### 動作確認 ![[Pasted image 20250223125121.png|frame]] ## Mermaid コードで図を表現するために[[Mermaid]]を使えるようにします。 ### マークダウンファイルに追加する ````markdown ```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ``` ```` ![[Pasted image 20250222222219.png|frame]] *コードのまま表示されてしまう* ### 設定変更 [[SuperFences (PyMdown Extensions)|SuperFences]]の設定を拡張するだけです。 ```yaml markdown_extensions: # 追加 - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid ``` ### 動作確認 ![[Pasted image 20250222222859.png|frame]] ## タスクリスト ### マークダウンファイルに追加する ```markdown ## タスクリスト - [ ] task1 - [x] task1-1 - [x] task2 ``` ![[Pasted image 20250222223903.png|frame]] *ただのリストしか認識されない* ### 設定変更 ```yaml markdown_extensions: - pymdownx.tasklist: custom_checkbox: true ``` > [!note] > `custom_checkbox: true` を設定しないと、見た目が[[HTML]]標準のチェックボックスになります。 ### 動作確認 ![[Pasted image 20250222223946.png|frame]] ## 脚注 ### マークダウンファイルに追加する ```markdown ## 脚注 文章の中に脚注[^n1]を入れられます。 [^n1]: 巻末に説明が表示されます ``` ![[Pasted image 20250223101111.png|frame]] *不正なリンクと判定されてしまう* ### 設定変更 ```yaml markdown_extensions: - footnotes ``` ### 動作確認 ![[Pasted image 20250223101149.png|frame]] *脚注が有効になり、区切り線と巻末説明が追加される* ## コードコピーボタン ### マークダウンファイルに追加する ~~~markdown ```python print("copy button") ``` ~~~ ![[Pasted image 20250226212724.png|frame]] *ホバーしてもコピーボタンは表示されない* ### 設定変更 ```yaml theme: features: - content.code.copy ``` ### 動作確認 ![[Pasted image 20250226213022.png|frame]] *ホバーするとコピーボタンが表示される* ## Markdown in HTML 表現に拘りたくなったとき、部分的に[[HTML]]を使いたいケースが出てきます。そのようなときに、[[HTML]]の中でも[[Markdown]]が使えると見た目がスッキリします。 ### マークダウンファイルに追加する ```markdown ## Markdown in HTML <div markdown="1" style="display: flex; gap: 4rem;">  | id | name | | - | - | | 1 | Ichiro | | 2 | Jiro | </div> ``` ![[Pasted image 20250223173749.png|frame]] *HTMLタグの内部は文字列として認識されるだけ* ### 設定変更 ```yaml markdown_extensions: - md_in_html ``` ### 動作確認 ![[Pasted image 20250223173851.png|frame]] *HTMLタグ内部のMarkdownも正しく表示される* > [!attention] > [[HTMLタグ]]に `markdown` 属性の指定 および 決められた値(ex: `"1"`)の指定が必要です。詳細は [[Markdown in HTML]] の仕様を確認してください。 ## インデントサイズ変更 インデントサイズ4は深すぎるので2にします。[[Mdx Truly Sane List]]プラグインを使います。 ### Mdx Truly Sane Listのインストール ```console pip install mdx_truly_sane_lists ``` ### 設定変更 ```yaml markdown_extensions: - mdx_truly_sane_lists: nested_indent: 2 ``` ## 外部リンクを常に新しいタブで開く 外部リンクをクリックしてしまうと、今見ているタブの内容がそのまま上書きされてしまいます。それを防ぐため、外部リンクは常に新しいタブはウィンドウで開くようにします。[[mkdocs-open-in-new-tab]]を使います。 ### mkdocs-open-in-new-tabのインストール ```console pip install mkdocs-open-in-new-tab ``` ### 設定変更 ```yaml plugins: - open-in-new-tab ``` # 設定の精査 ここまではプラグインや拡張機能の紹介をしてきました。最後は設定 (`mkdocs.yml`) を精査します。 ## テーマカラーの設定 [Primary colorを設定](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#primary-color)します。 ```yaml theme: palette: primary: teal ``` ![[Pasted image 20250223183903.png|frame]] *`teal`に設定した場合* ## ロゴとアイコンの設定 [Logoを設定](https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#logo)します。[[URL]]やローカルファイルパス、[[Material Design Icons]]などを指定できます。 ```yaml theme: icon: logo: material/coffee ``` ![[Pasted image 20250223184844.png|frame]] *Material Design Iconsから設定した場合* ## faviconの設定 [Faviconを設定](https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#favicon)します。 ```yaml theme: favicon: https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/favicon-64.png ``` ![[Pasted image 20250223185255.png|frame]] *[[favicon]]が[[みみぞう]]に* ## ページ表示の高速化 [Instant loadingを設定](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-loading)することで、[[SPA]]のようにページ内リンクによる移動でページを再読み込みせず、高速で画面遷移します。[[Obsidian Publish]]と同じような動きになります。 ```yaml # TODO: これを設定しないと静的デプロイしたサイトでは有効にならない # site_url: ... theme: features: - navigation.instant # 400ms以上かかるページ遷移に時間がかかる場合はページ上部にprogree barを表示 - navigation.instant.progress ``` > [!attention] > ページ表示速度が上がるかどうかは環境によります。場合によっては `navigation.instant` を指定しない方が速い可能性もありますので、実際に動作を比べて決めましょう。 細かいものが多いため本記事では割愛しますが、ナビゲーション設定項目は非常に数が多いので、一度目を通し、好みの設定にカスタマイズすることをオススメします。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://squidfunk.github.io/mkdocs-material/assets/favicon.png" /> <span class="link-card-v2-site-name">squidfunk.github.io</span> </div> <div class="link-card-v2-title"> Setting up navigation - Material for MkDocs </div> <div class="link-card-v2-content"> Write your documentation in Markdown and create a professional static site in minutes – searchable, customizable ... </div> <img class="link-card-v2-image" src="https://squidfunk.github.io/mkdocs-material/assets/images/social/setup/setting-up-navigation.png" /> <a href="https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation"></a> </div> ## URLの末尾を .html にする [[S3]]のような静的デプロイサイトでは `.html` のように拡張子で終わる[[URL]]が必要なケースもあります。[use_directory_urlsをfalseに設定](https://www.mkdocs.org/user-guide/configuration/#use_directory_urls)してURLを変更しましょう。 ```yaml use_directory_urls: false ``` `MkDocs` ページであれば以下のように変化します。 ```diff - http://localhost:8000/MkDocs/ + http://localhost:8000/MkDocs.html ``` ## WARNING発生時に処理を停止する [strictにtrueを設定](https://www.mkdocs.org/user-guide/configuration/#strict)することでWARNING発生時に処理を停止できます。 ```yaml strict: true ``` 通常、WARNINGが発生している場合はサイトのどこかが壊れているため、修正可能であれば修正することをお勧めします。 # 一発で環境構築するシェル これまでの設定やコマンドを一括して実行できる[[シェルスクリプト]]を書いてみました。最終成果物だけが欲しい場合は実行してみてください。 ```bash #!/bin/bash set -eu mkdir mkdocs-sample cd $_ mkdir docs cat > mkdocs.yml << 'EOF' site_name: MkDocs Sample strict: true use_directory_urls: false # TODO: site_url: これを設定しないと静的デプロイしたサイトでは有効にならない theme: name: material icon: logo: material/coffee repo: material/github favicon: https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/favicon-64.png features: - navigation.instant - navigation.instant.progress - content.code.copy palette: primary: teal plugins: - obsidian-bridge - awesome-nav - glightbox - open-in-new-tab - search: lang: ja - backlinks_section: title: "🖇️ Backlinks" description: "" add_to_toc: false hide_if_empty: true - git-revision-date-localized: enabled: !ENV [RELEASE, False] strict: false enable_creation_date: true locale: ja timezone: Asia/Tokyo - git-authors: enabled: !ENV [RELEASE, False] strict: false show_email_address: false markdown_extensions: - footnotes - md_in_html - obsidian_callouts - pymdownx.tilde - pymdownx.magiclink - toc: permalink: true slugify: !!python/object/apply:pymdownx.slugs.slugify {} - mdx_truly_sane_lists: nested_indent: 2 - pymdownx.snippets: check_paths: true base_path: docs - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid - pymdownx.tasklist: custom_checkbox: true - pymdownx.tabbed: alternate_style: true EOF cat > requirements.txt << 'EOF' mkdocs mkdocs-material # WARNINGが出なくなったらこちらを使う # mkdocs-obsidian-bridge git+https://github.com/tadashi-aikawa/mkdocs-obsidian-bridge mkdocs-awesome-nav mkdocs-backlinks-section-plugin mkdocs-git-revision-date-localized-plugin mkdocs-git-authors-plugin mkdocs-glightbox mdx_truly_sane_lists mkdocs-open-in-new-tab EOF cat > docs/.nav.yml << 'EOF' nav: - index.md - サンプル.md EOF cat > docs/index.md << 'EOF' Hello MkDocs & Obsidian !! - [[サンプル]] EOF cat > docs/サンプル.md << 'EOF' ## Callout > [!info] > INFOのCallout EOF python -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ファイル構成は以下の通りです。 ```console $ tree . ├── docs │ ├── index.md │ └── サンプル.md ├── mkdocs.yml └── requirements.txt ``` 作成が終わったら以下のコマンドでサイトを立ち上げましょう。 ```console cd mkdocs-sample git init && git add . && git commit -m "Initial commit" source .venv/bin/activate mkdocs serve ``` 今回は触れませんでしたが、デプロイするサイトのビルドとローカル起動は以下のコマンドで実行できます。 ```console mkdocs build python -m http.server -d site ``` # まとめ 以下の条件を満たす[[MkDocs]]プロジェクトのベース構築方法を紹介しました。 - [[Obsidian]]や[[obsidian.nvim]]で快適に管理できる - クローズドにデプロイ可能 - 無料 - 仕事にも使える なお、[[Obsidian]]や[[obsidian.nvim]]で編集するときは `docs` を[[Vaultルート]]にした方が色々と都合が良いと思います。