cf-pages-publisher

Trigger

User asks to publish, deploy, or share content as a web page. Examples:

• "把这个内容发布为网页"
• "Publish this as a page"
• "给我一个永久链接"
• "将这个 Markdown 文件部署为网页"

Setup (first-time only)

If <workspace>/config.json does not exist, run setup before publishing.

1. Collect from user

Ask the user through conversation:

• Project name — lowercase alphanumeric + hyphens, min 3 chars, determines https://<name>.pages.dev

Then choose ONE authentication method:

Method A: User provides .env file (preferred) Ask user to create <workspace>/.env with their credentials:

CLOUDFLARE_API_TOKEN=<token>
CLOUDFLARE_ACCOUNT_ID=<account-id>

Account ID is optional — will auto-detect if token has Account Settings:Read permission.

Method B: User provides credentials in conversation

• Cloudflare API Token — from https://dash.cloudflare.com/profile/api-tokens (needs "Cloudflare Pages:Edit")
• Cloudflare Account ID — required if token lacks "Account Settings:Read" permission. Find at: Cloudflare Dashboard → select domain → right sidebar.

2. Run setup script

# Method A: read credentials from .env file (preferred)
node <skill-dir>/setup.mjs --project <name> --auth env

# Method B-1: with token + account ID
node <skill-dir>/setup.mjs --project <name> --auth token --token <TOKEN> --account-id <ID>

# Method B-2: with token only (needs Account Settings:Read permission)
node <skill-dir>/setup.mjs --project <name> --auth token-only --token <TOKEN>

# Optional: custom workspace path (any method)
node <skill-dir>/setup.mjs --project <name> --workspace <path> --auth env

Default workspace: ~/.cf-pages-publisher/

Exit code 0 = success. On failure, read stdout for error details.

3. Verify

cat <workspace>/config.json

Must contain projectName, baseUrl, workspacePath. If missing, setup failed — check errors and retry.

Publish

1. Read config

cat <workspace>/config.json

2. Prepare content

If user provides text (not a file), write it to a .md file inside <workspace>/:

cat > <workspace>/<filename>.md << 'CONTENT'
<user content>
CONTENT

Ensure the content starts with a # Title heading.

3. Convert + Deploy

cd <workspace>
set -a && [ -f .env ] && source .env && set +a
npm run publish-doc -- <filename> --base <baseUrl>
npx wrangler pages deploy public --project-name=<projectName> --commit-dirty=true

4. Return URL

The last command outputs the deployment URL. Reply to the user with: <baseUrl>/<hash>/

publish-doc flags

Safety rules

• NEVER modify <workspace>/public/index.html — it is the auto-generated welcome page
• NEVER delete any <workspace>/public/<hash>/ directory — old links must stay alive
• NEVER clean or overwrite the public/ directory before deploy — always append only
• NEVER use --allow-html unless the user explicitly requests it — HTML is escaped by default for safety

Error recovery

For more details, read references/troubleshooting.md.