hoangvantuan/ghost-blog

Ghost Blog Management

Manage Ghost CMS posts and tags via Admin API.

Setup

1. Install Dependencies

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

2. Configure Environment

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

.env file:

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

Get your Admin API Key:

1. Go to Ghost Admin → Settings → Integrations
2. Create a Custom Integration
3. Copy the Admin API Key (format: id:secret)

3. Verify Setup

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

Quick Start

List posts:

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

Manage single post:

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

Bulk operations:

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

Manage tags:

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

Dispatch Rules

| User Intent | Script | Example Command | | ------------------------------------- | ------------------------- | ------------------------------------ | | test, run tests | pytest | cd scripts && uv run pytest -v | | list posts, show drafts, filter posts | posts_browse.py | --status draft --tag news | | get post, read post, show post | posts_crud.py get | --id xxx or --slug xxx | | create post, new post, write post | posts_crud.py create | --title "..." --html "..." | | update post, edit post, change post | posts_crud.py update | --id xxx --title "..." | | delete post, remove post | posts_crud.py delete | --id xxx --confirm | | publish post, publish draft | posts_crud.py publish | --id xxx | | unpublish post | posts_crud.py unpublish | --id xxx | | bulk publish, publish all drafts | posts_bulk.py publish | --filter "..." --execute | | bulk unpublish | posts_bulk.py unpublish | --filter "..." --execute | | add tag to posts, tag posts | posts_bulk.py add-tag | --filter "..." --tag xxx --execute | | remove tag from posts | posts_bulk.py remove-tag | --filter "..." --tag xxx --execute | | list tags, show tags | tags_manage.py list | (no options needed) | | create tag, new tag | tags_manage.py create | --name "..." | | delete tag, remove tag | tags_manage.py delete | --slug xxx --confirm |

Scripts

| Script | Purpose | | ----------------- | --------------------------------------------- | | ghost_core.py | Shared: JWT auth, HTTP client, error handling | | posts_browse.py | List, filter, search posts | | posts_crud.py | CRUD operations for single posts | | posts_bulk.py | Batch operations (publish, tags, featured) | | tags_manage.py | CRUD operations for tags |

Filter Syntax (NQL)

Ghost uses NQL for filtering:

# 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

Note: The --tag option in posts_browse.py accepts both tag names and slugs. It automatically resolves names to slugs via API lookup.

Creating Posts from Markdown Files

When creating posts from markdown files (e.g., a blog series):

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!

Important: Ghost 5.0+ uses Lexical editor format. The source=html param tells Ghost to convert HTML to Lexical. Without it, post content will be empty!

Fixing Internal Links

If markdown files have internal links like [Title](other-file.md), replace them with Ghost slugs after creating posts:

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

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

Safety Features

• Bulk operations: Preview mode by default

• Delete operations: Require --confirm flag

• API versioning: Uses Ghost v5.0 API

• HTML conversion: Auto-adds source=html param for Ghost 5.0+ compatibility

Testing

Setup Test Environment

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

Run Tests

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

Run with Coverage

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

Troubleshooting

| Error | Cause | Solution | | ---------------------------------- | -------------------------- | --------------------------------------------- | | "No virtual environment found" | Missing venv | Run uv venv in scripts directory | | "Failed to spawn: pytest" | Missing deps | Run uv pip install -r requirements.txt | | "GHOST_URL not set" | Missing .env | Copy .env.example to .env and configure | | "GHOST_ADMIN_KEY invalid format" | Wrong key format | Key must be id:secret format | | "UnauthorizedError" | Invalid API key | Check key is valid and has permissions | | "UPDATE_COLLISION" | Post modified | Retry operation (auto-refetches updated_at) | | Post content empty | Missing source=html | Ghost 5.0+ requires source=html param | | Tag filter returns 0 | Using name instead of slug | Use tag slug or let script resolve it | | HTTP 422 on tags list | Invalid params | Don't use include=count.posts or order | | Links point to .md files | Internal markdown links | Replace with Ghost slugs after creating posts |

References

• Ghost Admin API Docs

• NQL Filter Reference