| name | blog-authoring |
| description | Use when creating, editing, previewing, or publishing blog posts through the local working-copy flow, especially when the task involves `content/blog`, `npm run blog:*` commands, or `/blog-preview/...` URLs. |
Neon Blog Authoring
Default editing workflow:
- Work in the site repository.
- Edit the local working copy under
content/blog/.
- Run the local site to visually inspect the result.
- Publish the snapshot into the configured remote blog-content branch with the provided CLI.
Do not default to editing the remote source-of-truth repository directly unless the user explicitly asks for it.
Required checks
Before changing content, verify the current state:
git branch --show-current
npm run blog:status
If content/blog is missing, initialize it:
npm run blog:bootstrap
If the user explicitly wants to refresh the working copy from remote state:
npm run blog:sync -- --force
Core workflow
1. Edit locally
Edit only:
content/blog/posts/*.md
content/blog/authors/data.json
content/blog/categories/data.json
Then run:
npm run dev
Use the local app to review:
2. Publish to a branch in blog
Use the built-in CLI:
npm run blog:publish-branch -- --branch <branch-name>
Defaults:
- if
--branch is omitted, the current git branch name is used
- the command pushes the current
content/blog snapshot into the configured remote content repository
- the command prints preview URLs under
/blog-preview/...
3. Review branch preview
Open the generated preview URL, for example:
/blog-preview/<slug>?branch=<branch>&secret=<secret>
If the preview returns 404, treat that as “access denied or missing branch/slug”. Do not assume the route is public.
Guardrails
- Prefer
content/blog in the current repository as the editing surface.
- Do not overwrite existing
content/blog automatically; only use blog:sync -- --force when the user explicitly wants a refresh.
- Do not push to the main source-of-truth remote accidentally. If you must work in a separate source repo directly, inspect
git remote -v first and confirm which remote is safe to push to.
- When credentials are missing, limit yourself to local editing and local preview; explain exactly which publish/preview actions are blocked.
- Do not touch unrelated local files such as
src/scripts/compare-sites.js.
References
Load only what you need:
- Commands and environment expectations:
references/commands.md