Quartz5 の graph の日本語表示方法

Quartz とは、Obsidian のフォルダ（Vault）をほぼそのまま Web サイト化する静的サイトジェネレーターで、Markdown を HTML に変換し、リンク構造・タグ・グラフビューなどを保持したまま公開できます。ブログよりデジタルガーデンを作りたい人に向いています。

以下、Obsidian、Node.js、Git、GitHub、Quartz5 のインストール・登録等の設定が完了していいることが前提となります。

1. 日本語記事でグラフビューが正常に表示されない

日本語ファイル名の記事、日本語フォルダ下の記事では、現在の記事だけが孤立したノードとして表示されました。

原因は、Graph 内部で扱う次の slug 表現が一致していなかったためです。

• ブラウザURL
• 記事データのキー
• 内部リンクのリンク先

日本語URLはパーセントエンコードされるため、日本語記事でだけ不具合が発生します。

2. graph.inline.tsを日本語slug対応に変更した

次のファイルを編集しました。

.quartz\plugins\graph\src\components\scripts\graph.inline.ts

decodeURIComponent()とsimplifySlug()をまとめたnormalizeSlug()を追加し、次の値を同じ方法で正規化しました。

• 現在表示中の記事slug
• Graphデータ内の記事slug
• 内部リンクのリンク先slug
• 訪問済み記事のslug

併せて、グラフのノード名を日本語ゴシック体で表示するように変更しました。

3. Graphプラグインを再ビルドした

graph.inline.tsはソースファイルなので、公開用のdistも作り直す必要がありました。

npm install --include=dev
npm run build

これでdist内のJavaScriptにも変更が反映されました。

4. ローカルプレビューでは正常に反映された

npx quartz build --serve -o content-preview

※ content-preview フォルダをローカルプレビューフォルダに設定している場合

では、ローカルにある改変済みの

.quartz\plugins\graph

が使用されるため、変更が反映されました。

5. 公開サイトでは変更が反映されなかった

.quartzフォルダはGitの管理対象外だったため、改変したGraphプラグインはGitHubへ送られていませんでした。

GitHub Actionsでは、公開時に公式プラグインを改めて取得していたため、公開サイトでは改変前のGraphが使われました。

6. Graph公式リポジトリをフォークした

公式版、

quartz-community/graph

をフォークして、

githubAccountName/graph

を作成しました。

フォークをローカルへcloneし、改変したgraph.inline.tsをコピーしました。

..\GitHub\graph

その後、再ビルドして、srcとdistをフォーク側へpushしました。

7. Quartzの参照先をフォーク版へ変更した

quartz.config.yamlのGraph設定を、デスクトップ用・モバイル用ともに変更しました。

source: github:githubAccountName/graph

8. quartz.lock.jsonもフォーク版へ変更した

Graphの公式版とフォーク版は、どちらもプラグイン名がgraphです。

そのため、設定ファイルだけ変更しても、Quartzは既存の公式版Graphを「インストール済み」と判断していました。

そこで、quartz.lock.jsonのGraph項目を次の内容へ更新しました。

"source": "github:githubAccountName/graph",
"resolved": "https://github.com/githubAccountName/graph.git",
"commit": "フォーク版のコミットSHA"

その後、ローカルのGraphフォルダを削除し、ロックファイルから入れ直しました。

rmdir /s /q .quartz\plugins\graph
npx quartz plugin install --clean graph

npx quartz pluginで、次の表示になることを確認しました。

graph    github:githubAccountName/graph

9. GitHub Actionsのキャッシュが公式版Graphを残していた

GitHub Actionsでは、.quartz/pluginsをキャッシュしていました。

そのため、古い公式版Graphが復元され、フォーク版のコミットへ更新しようとして失敗していました。

ログには次のように表示されました。

graph: updating to ...
graph: failed to update

10. deploy.ymlでGraphだけ毎回入れ直すようにした

.github/workflows/deploy.ymlのインストール処理を次のように変更しました。

- name: Install Quartz plugins
  run: |
    rm -rf .quartz/plugins/graph
    npx quartz plugin install --clean graph
    npx quartz plugin install

最初はrun: |の|が抜けていたため、3行が1つのコマンドとして実行され、Actionsが失敗しました。|を追加して解決しました。

現在の構成

githubAccountName/graph
    改変したGraphプラグイン本体
 
quartz.config.yaml
    Graph の参照先を githubAccountName/graph に指定
 
quartz.lock.json
    使用するフォーク版のコミットを固定
 
deploy.yml
    Actions実行時にGraphの古いキャッシュを削除して再取得

つまり今回の作業は、単なる日本語対応だけでなく、

1. Graphのslug処理を修正
2. プラグインをビルド
3. フォーク版として管理
4. Quartzの設定とロックファイルを変更
5. GitHub Actionsのキャッシュ対策

まで行った、という流れです。