ghost-blog

Ghost ブログ管理

Admin API を使用して Ghost CMS の投稿とタグを管理します。

セットアップ

1. 依存関係をインストールする

cd .claude/skills/ghost-blog/scripts
uv venv
uv pip install -r requirements.txt

2. 環境を設定する

cd .claude/skills/ghost-blog/scripts
cp .env.example .env
# Edit .env with your Ghost credentials

.env ファイル：

GHOST_URL=https://your-blog.ghost.io
GHOST_ADMIN_KEY=your-key-id:your-secret-key
GHOST_API_VERSION=v5.0

Admin API キーを取得する：

1. Ghost Admin → Settings → Integrations に移動します
2. Custom Integration を作成します
3. Admin API キーをコピーします（形式：id:secret）

3. セットアップを確認する

cd .claude/skills/ghost-blog/scripts && uv run python ghost_core.py

クイックスタート

投稿を一覧表示する：

python scripts/posts_browse.py --status draft
python scripts/posts_browse.py --tag news --featured

単一の投稿を管理する：

python scripts/posts_crud.py get --id POST_ID
python scripts/posts_crud.py create --title "New Post" --html "<p>Content</p>"
python scripts/posts_crud.py publish --id POST_ID

一括操作：

python scripts/posts_bulk.py publish --filter "status:draft" --execute
python scripts/posts_bulk.py add-tag --filter "status:published" --tag "archive" --execute

タグを管理する：

python scripts/tags_manage.py list
python scripts/tags_manage.py create --name "Tutorial"

振り分けルール

ユーザーの意図	スクリプト	コマンドの例
テスト、テストを実行する	pytest	cd scripts && uv run pytest -v
投稿を一覧表示する、下書きを表示する、投稿を絞り込む	posts_browse.py	--status draft --tag news
投稿を取得する、投稿を読む、投稿を表示する	posts_crud.py get	--id xxx または --slug xxx
投稿を作成する、新しい投稿、投稿を書く	posts_crud.py create	--title "..." --html "..."
投稿を更新する、投稿を編集する、投稿を変更する	posts_crud.py update	--id xxx --title "..."
投稿を削除する、投稿を取り除く	posts_crud.py delete	--id xxx --confirm
投稿を公開する、下書きを公開する	posts_crud.py publish	--id xxx
投稿の公開を取り消す	posts_crud.py unpublish	--id xxx
一括公開する、すべての下書きを公開する	posts_bulk.py publish	--filter "..." --execute
一括で公開を取り消す	posts_bulk.py unpublish	--filter "..." --execute
投稿にタグを追加する、投稿にタグを付ける	posts_bulk.py add-tag	--filter "..." --tag xxx --execute
投稿からタグを削除する	posts_bulk.py remove-tag	--filter "..." --tag xxx --execute
タグを一覧表示する、タグを表示する	tags_manage.py list	（オプション不要）
タグを作成する、新しいタグ	tags_manage.py create	--name "..."
タグを削除する、タグを取り除く	tags_manage.py delete	--slug xxx --confirm

スクリプト

スクリプト	目的
ghost_core.py	共通機能：JWT 認証、HTTP クライアント、エラー処理
posts_browse.py	投稿の一覧表示、絞り込み、検索
posts_crud.py	単一の投稿に対する CRUD 操作
posts_bulk.py	一括操作（公開、タグ、注目記事）
tags_manage.py	タグに対する CRUD 操作

フィルター構文（NQL）

Ghost はフィルターに NQL を使用します：

# Status
status:draft
status:published
status:scheduled

# Tags (use slug, not name)
tag:news
tags:[news,tutorial]

# Featured
featured:true

# Combine (AND)
status:published+featured:true

# Combine (OR)
status:draft,status:scheduled

注： posts_browse.py の --tag オプションは、タグ名とスラッグの両方を受け付けます。API を照会して名前をスラッグに自動変換します。

Markdown ファイルから投稿を作成する

Markdown ファイル（例：ブログシリーズ）から投稿を作成する場合：

import markdown
from ghost_core import api_request

# 1. Convert Markdown to HTML
md_content = open('article.md').read()
html_content = markdown.markdown(md_content, extensions=['extra', 'nl2br'])

# 2. Create post with source=html (CRITICAL for Ghost 5.0+)
post_data = {
    'title': 'My Post',
    'html': html_content,
    'status': 'draft',
    'tags': ['my-tag']
}
response = api_request('POST', 'posts/',
                       data={'posts': [post_data]},
                       params={'source': 'html'})  # Required!

重要： Ghost 5.0 以降では Lexical エディター形式を使用します。source=html パラメーターを指定すると、Ghost が HTML を Lexical に変換します。指定しない場合、投稿の内容は空になります！

内部リンクを修正する

Markdown ファイルに [Title](other-file.md) のような内部リンクがある場合、投稿を作成した後に Ghost のスラッグへ置き換えます：

LINK_MAP = {
    'old-file.md': '/new-ghost-slug/',
}

html = html.replace('href="old-file.md"', 'href="/new-ghost-slug/"')

安全機能

• 一括操作：デフォルトではプレビューモードです

• 削除操作：--confirm フラグが必要です

• API バージョニング：Ghost v5.0 API を使用します

• HTML 変換：Ghost 5.0 以降との互換性のため、source=html パラメーターを自動的に追加します

テスト

テスト環境をセットアップする

cd .claude/skills/ghost-blog/scripts
uv venv
uv pip install -r requirements.txt

テストを実行する

cd .claude/skills/ghost-blog/scripts && uv run pytest -v

カバレッジ付きで実行する

cd .claude/skills/ghost-blog/scripts && uv run pytest -v --cov=. --cov-report=term-missing

トラブルシューティング

エラー	原因	解決策
"No virtual environment found"	venv がありません	scripts ディレクトリで uv venv を実行します
"Failed to spawn: pytest"	依存関係がありません	uv pip install -r requirements.txt を実行します
"GHOST_URL not set"	.env がありません	.env.example を .env にコピーして設定します
"GHOST_ADMIN_KEY invalid format"	キーの形式が正しくありません	キーは id:secret 形式である必要があります
"UnauthorizedError"	API キーが無効です	キーが有効で、必要な権限があることを確認します
"UPDATE_COLLISION"	投稿が変更されました	操作を再試行します（updated_at を自動で再取得します）
投稿の内容が空です	source=html がありません	Ghost 5.0+ では source=html パラメーターが必要です
タグフィルターの結果が 0 件です	スラッグではなく名前を使用しています	タグのスラッグを使うか、スクリプトに解決させます
タグ一覧で HTTP 422 が発生します	パラメーターが無効です	include=count.posts や order は使用しないでください
リンク先が .md ファイルです	内部の Markdown リンクです	投稿の作成後、Ghost のスラッグに置き換えます

参考資料

• Ghost Admin API のドキュメント

• NQL フィルターのリファレンス