Ghost CMS

说明文档

# Ghost CMS

Manage Ghost blog content, members, analytics, and newsletters through the Ghost Admin API.

## ⚠️ Security Warning

**Ghost Admin API keys provide FULL access to your Ghost site:**

- **Content Management:** Create, update, delete, publish posts and pages
- **Member Management:** Add, modify, delete members and subscriptions
- **Subscription Management:** Create, modify, delete membership tiers
- **Comment Management:** Reply to, approve, delete comments
- **User Management:** Invite, modify, delete users
- **Media Management:** Upload images and files (affects storage)
- **Site Configuration:** Modify newsletters and settings

**Published content is IMMEDIATELY PUBLIC** - be extra careful with publish operations.

**Security Best Practices:**
- **Store API keys securely** - Use 1Password CLI or secure env vars
- **Review before publishing** - Always check content before making it public
- **Never commit keys** - Keep credentials out of version control
- **Rotate keys regularly** - Create new integrations every 90 days
- **Use dedicated integrations** - Separate keys for different use cases
- **Test on staging first** - Use a test Ghost site when possible

**Admin API Key Scope:**
Ghost Admin API keys have **no scoping options** - they provide full access to everything. There are no read-only keys.

**Operation Types:**

**Read-Only Operations** (✅ Safe):
- List posts, pages, tags, members, tiers, newsletters, comments
- Get analytics and member stats
- All GET requests

**Destructive Operations** (⚠️ Modify or delete data, may be public):
- Create/update/delete posts, pages, tags (POST, PUT, DELETE)
- Publish/unpublish/schedule posts (**makes content public**)
- Create/update/delete members, tiers, newsletters
- Create replies, approve/delete comments
- Upload images (uses storage quota)
- All POST, PUT, DELETE requests

For detailed operation documentation, see [api-reference.md](references/api-reference.md).

## Quick Setup

1. **Get your Ghost Admin API credentials:**
   - Ghost dashboard → Settings → Integrations
   - Create a new "Custom Integration"
   - Copy the **Admin API Key** and **API URL**

2. **Store credentials securely:**

   **Option A: Environment Variables (Recommended)**
   ```bash
   # Add to your shell profile (~/.zshrc, ~/.bashrc)
   export GHOST_ADMIN_KEY="YOUR_ADMIN_API_KEY"
   export GHOST_API_URL="YOUR_GHOST_URL"
   ```

   **API URL Examples (works with ALL hosting types):**
   ```bash
   # Ghost(Pro) hosted
   export GHOST_API_URL="https://yourblog.ghost.io"
   
   # Self-hosted with reverse proxy (production)
   export GHOST_API_URL="https://blog.yourdomain.com"
   
   # Self-hosted development (Ghost default port 2368)
   export GHOST_API_URL="http://localhost:2368"
   
   # Self-hosted with custom port
   export GHOST_API_URL="https://ghost.example.com:8080"
   ```

   **Important:**
   - Always include protocol (`http://` or `https://`)
   - Include `:PORT` if Ghost runs on non-standard port
   - Do NOT include trailing slash
   - Do NOT include `/ghost/api/admin` (added automatically)

   **Option B: Config Files**
   ```bash
   mkdir -p ~/.config/ghost
   echo "YOUR_ADMIN_API_KEY" > ~/.config/ghost/api_key
   echo "YOUR_GHOST_URL" > ~/.config/ghost/api_url
   
   # Secure the files (owner read-only)
   chmod 600 ~/.config/ghost/api_key
   chmod 600 ~/.config/ghost/api_url
   ```

   **Option C: 1Password CLI (Most Secure)**
   ```bash
   # Store key in 1Password
   op item create --category=API_CREDENTIAL \
     --title="Ghost Admin API" \
     admin_key[password]="YOUR_ADMIN_API_KEY" \
     api_url[text]="YOUR_GHOST_URL"

   # Use in commands
   export GHOST_ADMIN_KEY=$(op read "op://Private/Ghost Admin API/admin_key")
   export GHOST_API_URL=$(op read "op://Private/Ghost Admin API/api_url")
   ```

   **Security Notes:**
   - Keys provide **full site access** - protect them like passwords
   - Rotate keys every 90 days (create new integration, revoke old)
   - Never commit to git or share keys publicly
   - Consider separate keys for production vs. staging
   - **HTTPS recommended:** Use HTTPS for production (HTTP acceptable for localhost only)

3. **Install dependencies:**
   ```bash
   cd ghost-cms-skill/scripts
   npm install
   ```

   **Dependencies installed:**
   - `form-data` (^4.0.5) - Multipart file uploads (theme ZIP files)
   - `jsonwebtoken` (^9.0.3) - JWT token generation for Ghost Admin API authentication

   **Optional dependencies** (install manually if needed):
   - `gscan` (^5.2.4) - Official Ghost theme validator (from TryGhost)
     - Only needed for theme validation feature
     - Install with: `cd scripts && npm install gscan`

   **All dependencies from public npm registry. No custom downloads.**

4. **Test connection:**
   See [setup.md](references/setup.md) for detailed authentication and troubleshooting.

## Tools & Utilities

### Snippet Extractor

**Purpose:** Migrate existing Ghost snippets to local library for programmatic use.

**Why needed:** Ghost Admin API blocks snippet access (403 Forbidden) for integration tokens. This tool works around that limitation.

**Usage:**
```bash
# Extract snippets from a specially-formatted draft post
node scripts/snippet-extractor.js my-snippets-post

# Validate format before extracting
node scripts/snippet-extractor.js my-snippets-post --validate

# Preview without saving
node scripts/snippet-extractor.js my-snippets-post --dry-run

# Custom marker prefix
node scripts/snippet-extractor.js my-snippets-post --marker "This is:"

# Full help
node scripts/snippet-extractor.js --help
```

**Workflow:**
1. Create draft post in Ghost
2. For each snippet: add paragraph marker (e.g., "SNIPPET: name" or "This is: name")
3. Insert the snippet content below each marker
4. Run extractor → all snippets saved to `snippets/library/`

**Features:**
- ✅ Extracts all card types (bookmarks, callouts, images, markdown, HTML, etc.)
- ✅ Preserves exact Lexical structure
- ✅ Auto-detects credentials from `~/.config/ghost/` or env vars
- ✅ Supports custom marker formats
- ✅ Dry-run and validation modes
- ✅ Verbose output for debugging

**Example:**
```bash
# User has 12 snippets in Ghost
# Creates "My Snippets" draft with markers
# Runs: node scripts/snippet-extractor.js my-snippets --marker "This is:"
# Result: All 12 snippets in library/ ready for use
```

See `snippets/README.md` for complete documentation.

### Theme Manager

**Purpose:** Upload, activate, switch, and manage Ghost themes programmatically.

**Why needed:** Automate theme deployments, switch themes, manage theme versions.

**Usage:**
```bash
cd scripts

# List all installed themes
node theme-manager.js list

# Upload theme ZIP
node theme-manager.js upload /path/to/theme.zip

# Upload and activate immediately
node theme-manager.js upload /path/to/theme.zip --activate

# Activate existing theme
node theme-manager.js activate theme-name

# Download theme backup
node theme-manager.js download theme-name backup.zip

# Delete theme (cannot delete active theme)
node theme-manager.js delete old-theme

# Show current active theme
node theme-manager.js active
```

**Features:**
- ✅ Upload custom themes from ZIP files
- ✅ Switch between installed themes
- ✅ Download theme backups
- ✅ Delete unused themes
- ✅ Validation and error handling
- ✅ **Immediate activation** - theme changes are public instantly

**⚠️ Important:**
- Theme activation is **immediate and public** - site appearance changes instantly
- Cannot delete the currently active theme (switch first)
- Themes must be valid Ghost theme ZIP files

**Workflow:**
```bash
# Safe theme switching with rollback
node theme-manager.js active              # Note current theme
node theme-manager.js activate new-theme  # Switch to new theme
# Test site in browser
node theme-manager.js activate old-theme  # Rollback if needed
```

See `references/themes.md` for complete theme management documentation and best practices.

### Theme Validator

**Purpose:** Validate Ghost themes before uploading using official gscan validator.

**⚠️ Optional Feature:** Requires `gscan` package. Install with:
```bash
cd scripts
npm install gscan
```

**Why needed:** Catch errors early - missing files, invalid syntax, deprecated helpers, version incompatibility.

**Usage:**
```bash
cd scripts

# Validate theme directory
node theme-validator.js ~/themes/my-theme/

# Validate ZIP file  
node theme-validator.js theme.zip

# Target specific Ghost version
node theme-validator.js theme.zip --version v6

# JSON output for CI/CD
node theme-validator.js theme.zip --json

# Show only errors (hide warnings)
node theme-validator.js theme.zip --errors-only
```

**Features:**
- ✅ Official Ghost validator (gscan from TryGhost)
- ✅ Same validation as Ghost Admin
- ✅ Validates directories or ZIP files
- ✅ Ghost v5/v6 compatibility checking
- ✅ Finds deprecated helpers and syntax errors
- ✅ CI/CD integration (JSON output, exit codes)
- ✅ Categorized issues (errors, warnings, recommendations)

**Validation levels:**
- **Errors** - Must fix before upload (theme will be rejected)
- **Warnings** - Should fix for best compatibility
- **Recommendations** - Nice to have (best practices)

**Safe deployment workflow:**
```bash
# 1. Validate before upload
node theme-validator.js my-theme.zip

# 2. Fix any errors

# 3. Re-validate
node theme-validator.js my-theme.zip

# 4. Upload when clean
node theme-manager.js upload my-theme.zip
```

**CI/CD integration:**
```bash
node theme-validator.js theme.zip --json
if [ $? -eq 0 ]; then
  node theme-manager.js upload theme.zip --activate
fi
```

**Exit codes:** 0 = valid, 1 = errors found, 2 = invalid arguments

See `references/themes.md` for complete validation documentation and common error fixes.

---

## Core Operations

This skill covers all major Ghost operations. Navigate to the relevant reference for detailed guidance:

### Content Management
**When to use:** Creating drafts, publishing posts, scheduling content, managing pages

See **[content.md](references/content.md)** for:
- Creating new posts (drafts)
- Publishing and scheduling posts
- Updating existing content
- Managing tags, featured images, metadata
- Working with pages vs posts

See **[lexical-cards.md](references/lexical-cards.md)** for:
- **Complete Lexical card type reference** (23 documented types)
- Most comprehensive Ghost Lexical documentation available
- Full JSON structures with field references
- Video, audio, file uploads, buttons, toggles, embeds
- Product cards, headers, call-to-action, paywall
- Member visibility and content personalization

**⚠️ Ghost Snippets Limitation:**

Ghost's native snippet feature (reusable content blocks saved in the editor) **cannot be accessed via the Admin API** with integration tokens (403 Forbidden). This means:

- ❌ Cannot list available snippets
- ❌ Cannot fetch snippet content
- ❌ Cannot programmatically use author's existing snippets

**Solution: Automated Snippet Extraction**

The skill includes a **snippet extractor tool** that migrates Ghost snippets to local files:

1. **Create extraction post** in Ghost with all snippets (one-time setup)
2. **Run extractor:** `node scripts/snippet-extractor.js post-slug`
3. **Done!** All snippets saved to `snippets/library/` for programmatic use

**Commands:**
```bash
# Extract snippets (auto-detects credentials from ~/.config/ghost/)
node scripts/snippet-extractor.js my-snippets-post

# Validate format before extracting
node scripts/snippet-extractor.js my-snippets-post --validate

# Preview without saving
node scripts/snippet-extractor.js my-snippets-post --dry-run

# Custom marker format
node scripts/snippet-extractor.js my-snippets-post --marker "This is:"

# Full help
node scripts/snippet-extractor.js --help
```

**Benefits:**
- ✅ Migrate all existing Ghost snippets in seconds
- ✅ Preserves exact Lexical structure (bookmarks, callouts, images, etc.)
- ✅ Git version control
- ✅ Use programmatically in automated posts
- ✅ W...