Quartz v5へ移行した記録

Obsidianのノートの一部をQuartzで公開している。
とは言っても不具合がでてそのまま放置していたのでだいぶ間が空いている。

これまではQuartz v4を使っていたのだけれど、Quartz v5が出ていたので、この機会に移行することにした。

v4を入れたときは、公式ドキュメントを見たり、他の人のサイトを見たり、「これどうやるんだ？」と調べながら自分で設定していった記憶がある。
→ Quartz4をインストール

今回はかなり違った。

ほぼChatGPTと相談しながら設計を決めて、実際の作業はCodexにやってもらった。

私はというと、出てきたものを見て、

「それでいい」
「そこは違う」
「これは前の方が好き」
「本当に大丈夫？」

とか言っているくらいだった。

ずいぶん楽になった。

ただ、終わってみると単純なQuartz v4 → v5のバージョンアップではなく、ObsidianからWebへ公開する仕組み自体をかなり作り直していた。

v4をアップデートするのではなく、新しく作った

最初に決めたのは、今あるQuartz v4をそのままv5にアップデートしないこと。

旧環境とは別に、Quartz v5を新しく作ることにした。

v4の環境には、これまで使ってきた設定やCSSなどがいろいろ入っている。

それを全部そのまま持っていけば見た目は近くなるかもしれないけれど、今となっては「これ何のために入れたんだっけ？」というものもある。

だったら一度まっさらなQuartz v5から始めて、本当に必要なものだけ持ってくればいい。

サイト名、日本語設定、色やフォント、Explorer、Recent Notes、TOCなど、使いたいものは移した。

逆に、v4と完全に同じ見た目にすることにはこだわらなかった。

Quartz v5で普通にできることなら、できるだけv5の標準に乗る。

今回はその方針で進めた。
これもChatGPTの助言で決めたのだけれどね。

一番変えたかったのは公開方法

Quartz v5にしたかった、というより、実はこっちの方が大きかったかもしれない。

Obsidian Vaultを正本にしたかった。

公開用の記事をどこか別のフォルダへコピーして管理するようなことをやめることにした。

これはQuartz4の時にObsidian vaultの中にQuartzを入れて運用してきた中で感じたこと。

Obsidianで普段使っているノートが本物で、公開サイト側はそこから作られるものにしたい。

なので、公開したいノートにはFront Matterで、

publish: true

を付けることにした。

これが付いているノートだけをQuartzへ持っていく。

Quartz側の content は、自分で編集する場所ではなく生成物という扱い。

記事を公開したければ publish: true。

公開をやめたければ外す。

かなり分かりやすくなった。

非公開ノートへのリンクをどうするか

ここはObsidianならではの問題があった。

私はWikiLinkを普通に使っているので、公開するノートの中から非公開ノートへリンクしていることもある。

そのままQuartzへ持っていくわけにはいかない。

公開していないノートなのに、そのノート名だけ外へ出てしまうのも嫌だし、当然transclusionで本文が出てしまうのはもっと困る。

なので、

• 公開ノートへのリンクは普通にリンクする
• 非公開ノートへのWikiLinkはリンクにはせず、文字だけ残す
• 安全に処理できない埋め込みなどがあれば、勝手に公開せず処理自体を止める

という形にした。

これを書いているこのノートからも、元になったSessionLogへWikiLinkを貼っておけばいい。

Obsidianの中では元の記録へ辿れる。

でもSessionLog自体は公開しないので、Webではリンクにならずノート名だけが表示される。

SessionLogはSL20260924_001
このSessionLogをもとに公開記事を書いた。

これは結構気に入っている。

何かあったときには元の記録へ戻れるけれど、そのためにSessionLogまで公開する必要はない。

URLも整理した

これまで使っていたFront Matterの slug も、この機会に permalink へ移した。

Hugoを使っていたときから採用し、ObsidianでもノートにUIDを付与するのにも役立っていた。
いわゆるユニークノートみたいに命名している。

どうせ移行するなら、古い形式を使い続けるための互換処理を入れるより、一度全部揃えてしまった方がいい。

記事をObsidian内で別のフォルダへ移動しても、公開URLは変わらないようにしたかった。

私はVault内のノートを後から移動することが結構ある。

そのたびにブログの記事URLまで変わるのは困る。

なので、

Vault内の場所とWeb上のURLは別物

として扱うことにした。

ただ、トップページだけは少し特殊だった。

permalink: /

と書けばそのままトップページになると思っていたのだけれど、Quartz v5ではそう単純ではなかった。

ここは公開処理側で専用の対応を入れることになった。

まあ、この辺は公式キュメントと実際の矛盾があったりして、issueだしたり、ChatGPTとCodexに迂回策を実装してもらったりとこれだけで記事書けることもあったりした。

俺環での迂回策なので、他の人の参考になるかわからないが迂回策を公開するのもネタとしてあり。

GitHubからNetlifyへ公開

Quartz v5側がある程度できたところでGitHubとNetlifyを接続した。

流れとしては、

Obsidianでノートを書く  
↓  
公開対象をQuartzへ同期  
↓  
GitHubへpush  
↓  
Netlifyでbuild  
↓  
サイトへ反映

という形。

いきなり今のドメインを新サイトへ向けるのは怖いので、まずはNetlify側のURLで動かした。

記事は出ているか。
リンクは大丈夫か。
非公開の記事が出ていないか。
RSSやsitemapはどうか。

そのあたりを確認してから独自ドメインを新しいQuartz v5へ切り替えた。

旧サイトもすぐには消さずに残した。

何かあったときに戻せる方がいい。

こういう移行作業は、「新しい方が動いた」だけではなく、「何かあったら戻せる」状態で進める方が安心する。

旧Quartzに残っていた記事も戻した

ここで、もう一つ整理が必要になった。

昔のQuartz側に記事が残っていた。

今回の設計ではObsidian Vaultが正本なので、Quartz側にしか存在しない記事がある状態はよろしくない。

そこで旧Quartzの記事を確認して、Vaultへ戻した。

そのまま公開を続けるものもあれば、Vaultには残すけれど非公開にするものもある。

昔の記事なので、今見ると「これはもう公開しなくてもいいかな」というものもあった。
が結局基本的に公開のままにしている。

URLについては、できるだけ以前のものを維持することにした。

せっかく過去に公開していたものなので、移行しただけでURLを全部変えてしまう必要もない。

古いQuartzを消した……はずだった

新しいQuartz v5も動いた。

記事も移した。

じゃあ旧Quartzを消して終わり。

……とはならなかった。

一度消したはずの旧Quartzのフォルダが、後からまた現れた。

最初は何が起きているのかよく分からなかった。

調べていくと、別の端末側にはまだ旧Quartzの実体が残っていた。

Obsidian Syncを使っているので、その影響で削除したはずのものがまた見えてきた可能性が高かった。

この辺は今回かなりややこしかった。

最終的には、残っていた旧環境を確認して、必要なものを保全してから削除。

他の端末にも削除が同期されて、旧Quartzがなくなったところまで確認した。

Quartzのバージョンアップ記事なのに、最後はなぜかObsidian Syncと戦っていた。

でも複数端末でVaultを使っている以上、こういうこともあるんだなというのは覚えておきたい。

日本語の改行がおかしい

途中、iPhoneでサイトを見ていて別の問題にも気付いた。

日本語の文章の右端が妙にガタガタしている。

なんというか、左に寄って見える。

最初は本文幅かなと思った。

Gridか？
フォントか？
iPhoneだからか？

いろいろ調べた。

最終的には、もっと単純なCSSの問題だった。

これも別記事にした方が同じく悩むQuartz利用者の参考になると思う。
とはいえ、ChatGPTと一緒に原因特定できないところに@ぷらはちゃんが颯爽とやってきて教えてくれた。まじ感謝🥲

• Quartz v5で日本語の改行が不自然だった原因はtext-wrap: prettyだった

今回はほとんどCodexにやってもらった

今回の移行で一番印象に残ったのは、実はQuartz v5そのものではないかもしれない。

v4を作ったときとは、作業の仕方がまったく違った。

以前なら、

公式ドキュメントを読む。
検索する。
設定ファイルを見る。
試す。
失敗する。
また検索する。

という感じだった。

今回はChatGPTに、

「こういう環境にしたい」
「今はこうなっている」
「ここは残したい」
「これはいらない」

と話して、ある程度方針を固める。
それをCodexにやってもらう。
結果を見て、またChatGPTと相談する。

だいたいそんな流れだった。

私はコードをほとんど書いていない。
もともと書けないので、もっぱらネットのコードをコピペしていただけだから不具合起きても自己解決できなかった。

それがいまや途中、結構大きな変更をしているのに、私はボケーっと進捗を見ていた時間の方が長かった気がする。

それでも最終的に以前より自分の使い方に合った環境になった。

これはなかなか面白い。

AIに任せると何も考えなくてよくなる、という感じではなかった。

むしろ、

自分が最終的にどうしたいのかを決めることの方が重要になった。

設計はChatGPTがかんがえてくれて、実装方法はCodexが考えてくれる。

でも、

• 公開記事の正本はどこなのか
• 非公開リンクをどう扱うのか
• 昔のURLを残すのか
• v4の見た目をどこまで引き継ぐのか

みたいなことは、こっちが決めないといけない。

私はそっちだけ考えていればよくなった。

これはかなり楽だった。

今はどうなったか

最終的には、

Obsidianで普通にノートを書く。

公開したくなったら publish: true を付ける。

公開処理を実行する。

それだけでQuartz側へ反映できる形になった。

Quartz側の記事を直接いじる必要もない。

Vault内でノートを移動してもURLは維持できる。

非公開ノートへのリンクも、そのまま外へ出ない。

最初は
「数年に一度のブログ書きたい熱が上がってきたぞ🤒
Quartz v5が出ているし移行するか
今ならChatGPTとCodexがいるから無敵」
くらいだったのだけれど、結果的には公開環境を丸ごと整理することになった。

v4を作ったときより、自分で調べた量も、自分でコードを書いた量も圧倒的に少ない。

それでも、今回の方がちゃんと「自分がどう使いたいか」を考えて作った気がする。

まあ、実装したのはほぼChatGPTとCodexなんだけど。