Astro × ヘッドレスCMS で技術ブログを作る

概要

もともとはAstro + microCMSで技術ブログを作っていたが、マークダウンのサポートが手薄く、エディタの使用感も好みではなかった。

• 記事をマークダウンで書きたい
• 書いた記事はgitで管理したい（変更差分の追跡や、作業したことをGithubの草に反映したい）

と思い、Sveltia CMS上でマークダウンで記事を書き、マークダウンファイルを生成してAstro Content Collectionでマークダウンファイルを管理することにした。

その過程で記事が生成されるディレクトリのサブモジュール化や、AstroとDecap/Sveltia CMS連携などを行ったのであたりの知見をメモとしてまとめる。

使用技術の変遷

使用する技術を変えるたびに、思うところが出てきてそのたびに更新してきたので、その一連の流れをざっくりと書いていく。

1. Astro + microCMS

一番最初にブログサイトを作ってみようと思い立った時にAstroを学び始めていたこともあり、ヘッドレスCMSと統合して記事の管理はCMS、UIはAstroで作ろうという思いヘッドレスCMSを探していた。 日本発のヘッドレスCMSということで何となくmicroCMSを選定して実際に繋ぎこんでみた。 APIをカスタマイズすることができて、そのAPIをもとにAstroからコンテンツを取得できるのはわかりやすさや拡張性の面でいいなと思いつつ、このCMSはWordPress同様独自のリッチテキストエディタが採用されていて、マークダウンで記述するには非公式プラグインを入れるなどをしないといけなかったり、細かいバグ（エディタに文字を入力できない時があるなど）があったりしたので別のヘッドレスCMSへの移管を考え始めた。

変更理由

• マークダウンでの記述は実現はできるが、APIレスポンスに不満はある（HTMLパースが必要になったり）
• エディタの細かいバグが気になる

2. Astro Content Collection + hygen

使い慣れた形式でもあり、ZennやNotionで書いた記事をコピペで崩れることなく移行できるのも利便性がいいためマークダウンで記事を書きたかった。

AstroはContent Collectionという、マークダウンファイルの内容をパースしてAstroファイルで使用できるようにするという機能があるのでそれを使えばいいかと思い、Astroプロジェクト内でマークダウンを追加して記事を書き、その内容を表示させることにした。

Astroプロジェクト内でマークダウンファイルを管理するので、記事がgit管理できるという点もよかった。

ただ、ヘッドレスCMSなどと連携しなければVSCodeなどのエディタで記事を書かなければいけなく、毎回マークダウンを手動で作成してフロントマターもコピペして…という作業が大変だったので、テンプレートくらいは作成したいなと思い、hygenを採用。（さらに言うと後述するObsidianでの記述もこの時点で検討した）

hygen - Github

変更理由

• マークダウン形式で書ける上に、git管理もできてやりたいことは実現できたが、フロントマターで管理する記事のカテゴリの入力が手動で面倒だった

例えば以下のように、フロントマターに定義したカテゴリをUIに出力しているのだが、これはただのマークダウンファイルなので定義済みのカテゴリを表示するサジェスト機能などもなく、カテゴリは手作業で追加する必要があった。zodを使って定数管理しているカテゴリのみを受け付けるようにしているので、定義されていないカテゴリを使おうとしたら実行時エラーは出るのだが、手動での入力なためタイポもしてしまうことも少なくなかった。

// astro.md
---
categories: ["Astro","SSG"]
---
## Astroについて
Astroは、ブログやマーケティング、eコマースなど、コンテンツ駆動のウェブサイトを作成するためのウェブフレームワークです。Astroは...

• ローカルだけじゃなくてマルチデバイス（異なるPC間、スマートフォンなど）で記事を書けるようにしたくなった（git pullを各デバイスで行うのはとても面倒なのでリアルタイムな同期が理想）。

3. Decap CMS（旧: NetlifyCMS）

マークダウン形式で書くことができ、保存したらつなぎこんだリポジトリに直接pushされ、マークダウンファイルが生成される。git管理可能なマークダウン形式のヘッドレスCMS。 管理画面でカテゴリがサジェストで表示されるようになったのはかなりうれしかった。 元NetlifyCMSだったらしく、その名の通りNetlifyにホスティングしないとダメそうだったので、AmplifyにホスティングしていたものをNetlifyへ移管。

変更理由

• UI/UXがそこそこ悪い
• 記事プレビューやスマートフォン表示時のUIの質が特に悪い（レスポンシブ×）

4. Sveltia CMS

これが現在使っているもの。 DecapCMSの互換性があって、とにかく移管が楽（OAuth周りは少し調整必要かも）。 Decapの全欠点を解消。モバイル対応・UI/UXともに大幅によくなった。

ここまでで、

• 記事はすべてマークダウンで書ける
• Git管理が可能
• マルチデバイスで記事を書くことができてリアルタイムのデータの同期が可能
• ヘッドレスＣＭＳはエディタと比べて、メタデータの管理がしやすい

といったようないい体験を求めて使用する技術を変えてきたけど、もう一つ解決したい不満があった。

記事の編集履歴をプライベートに閉じる

記事をGit管理することで、記事の更新差分を見ることができたり、記事を更新したときにGithubにその作業履歴が残り草に反映させることができた。

ただ、ただ単に記事をgit管理すると下書きレベルの拙い文章や、publicにしたくない重要な記述（技術ブログというのもあり、ソースコードの添付などをするときに誤ってシークレットキーなどが含まれていたり）などがあると思うので、

Astroプロジェクト（ブログ本体）自体はpublicにして、マークダウンファイルが集約されるディレクトリ（src/content/{posts_name}）のみをprivateリポジトリにしたく、このディレクトリをsubmoduleとして切り出すことにした。

そうすることで、マークダウンファイルの変更履歴はきちんと積み重なり、自分だけがその差分を確認できるという状況を作ることができる。

サブモジュール運用

• 親リポジトリ：astro-markdown-blog（Astro本体＋UI・CMS連携・公開用）
• サブモジュール：blog-posts（Markdown記事＋imagesを全てここに集約、private運用）

astro-markdown-blog/        # 親リポジトリ（Astro）
└── src/
    └── content/
        └── posts/         # サブモジュール（記事）
            ├── images/
            ├── foo.md
            └── bar.md

構成は上記になったが、いくつかの問題はあった。

サーバー側でsubmoduleの初期化ができない

サーバー側でデプロイ前に

git submodule update --init --recursive

を実行して、.gitmodulesの内容をもとにサブモジュールの初期化を行うのだが、その際にprivateリポジトリなサブモジュールを取得できずデプロイが始まらなかった。 privateなリポジトリにアクセスするための必要情報が足りず、エラーでデプロイが止まっていた。

// .gitmodules

[submodule "src/content/posts"]
　　path = src/content/posts
　　url = git@github.com:k-ito-cat/blog-posts.git
　　branch = main

やり方の詳細は調べたらすぐ出てくるので省くが、GithubでDeploy keyを発行してNetlifyに公開鍵を登録するだけ。

SveltiaCMSで記事作成後、Netlifyのデプロイが走らない

SveltiaCMSで記事作成・更新などをした後、サブモジュールのリポジトリに直接pushされるのでサブモジュールは更新されるけど、ブログ側のリポジトリが更新されないので変更が検知されず、Netlifyのデプロイが走らなかった。

結論、Github actionsでいろいろやって無理やり解決させた。 流れは

CMSで保存時にサブモジュール(blog-posts)にcommit/pushが走る
    ↓
サブモジュールのGitHub Actionsでスーパープロジェクト（親リポジトリ）にイベント通知
    ↓
スーパープロジェクトのGitHub Actionsで、サブモジュールからイベントの通知を受け取った後、 submodule update → commit & push（スーパープロジェクトでサブモジュールの変更差分を取り入れる必要があるのでそれをしている。ポインタの更新と呼ばれる作業）
    ↓
ひとつ前の commit & push によってリポジトリに変更が加わりNetlifyが検知してデプロイ開始される

といったようにCMSで変更を加えたらデプロイまでの流れをGithub Actionsで自動化した。

ビルド・デプロイ

AmplifyからNetlifyに移行した兼ね合いでビルド設定をtomlファイル用にした。

Netlifyだとコンソールでビルド設定書くのがやりにくいのでnetlify.tomlを作ることが多いのかも。

[build]
command = "git submodule update --init --recursive && npm ci --cache .npm --prefer-offline && npm run build"
publish = "dist"

[build.environment] 
NODE_VERSION = "22.13.0"

AstroとCMSとの連携・認証

このあたり実装途中あんまりメモ取れなかったのと、深く理解できていない部分はあるのでさらっと書く。

Decap CMS

• npmモジュールなどは不要

public/admin/index.htmlを以下のドキュメントに沿って作成するだけで管理画面が作成完了する。Astroならpages/admin/index.astroでもいいので自分はそうしている。

https://decapcms.org/docs/install-decap-cms/

• 管理画面のつなぎこみ設定やメタデータ管理などはconfig.ymlで行う
• CMSに書き込み許可するためgithubログインが必要（ログインユーザーがつなぎこんだサブモジュールのprivateリポジトリへのアクセス権があれば記事の作成や更新などが可能）。

OAuth appとOAuth認証用のハンドラが必要だった（privateリポジトリでなければNetlify Identity + Git Gatewayで簡単にできたらしい）。ハンドラについてはさすがに作りたくなかったのでnpmのパッケージを使った。SSRモードじゃないと動かなかったので注意。 OAuth appについては https://github.com/settings/developers 「OAuth app」から新規作成する。 callbackにはhttps://{自分のサイト}/oauth/callbackを追加する必要がある。

https://www.npmjs.com/package/astro-decap-cms-oauth

Sveltia CMS移行と注意点

sveltia-cms

移行は最小限で済んだ。 ドキュメントにある通り、CDNの読み込み先を変更するだけ。 （真っ白な画面になったりしたのでDecapからの移行時はキャッシュとか非同期で読み込んでみるとかで調整したほうがいいかもしれない）

OAuthのハンドラなどはSveltiaが内包しているようで、ひとつ前のセクションでやったことは不要になった。

OAuthのハンドラは不要になったが、OAuth appは新規で作成して、NetlifyのOAuth設定(client idとシークレットの登録)は必要

// OAuth app
Application name: 任意
Homepage URL:  https://{name}.netlify.app）
Authorization callback URL: https://api.netlify.com/auth/done

Sveltia CMSのエラーと回避策

Sveltia CMSで記事の新規作成時、「A path was requested for deletion which does not exist as of commit oid」エラーが出て記事を作成できなかった。

記事を全削除したり、slugや画像の日本語をすべて英字に変えたりしてみても解決せず、何が原因かわからないままこれまで使っていたblogとは別のコレクション（src/content/posts/test）を作成したらその中では記事が作成できた。

これまでposts直下にmdファイルを管理していたが、 blog用mdをblog等のサブディレクトリに移動・folderも合わせることでエラーが解消した。 おそらく/postsのなかに.github/workflowなどがあったのでこれが影響していそうではあるが、DecapCMSでは奇跡的にうまく動いてたので問題なかったが、DecapCMSから移行するときは一応注意したほうがよさそう。

ひとまず移行後は 管理画面UIが大幅改善して、モバイル対応・プレビュー崩れも少なく満足している。 下書きやslug編集もデフォルトで対応されていて（Decapにはなかった）、使いやすい。