How to Build an Editorial Review and Publishing Workflow

Shipping documentation from a chat transcript into production without a gate is how incorrect claims and unfinished covers go live. An editorial review workflow keeps drafts private, records what changed, and requires an explicit human approval before native content updates.

Separate private work from the public tree

Approved pages live in the native Docusaurus content directories that the build scans. New drafts and revisions belong in a sibling private work directory configured beside the project. A normal npm run build must not discover unfinished Markdown or unapproved images.

That separation gives reviewers a stable production tree while writers iterate. It also makes discard safe: rejecting private work leaves published pages and shared approved assets untouched.

Identify work by stable ids

Use a stable content id that survives title or slug edits. Create a draft for new work or begin a revision against an already approved page. Register prose when the Markdown is intentional—registration recomputes a proposal digest from the Markdown, destination, type, slug, and declared managed assets.

If you change the article after registration, review becomes invalid until you register again. Image tools that return change receipts must be registered before another write on the same article so digests stay honest.

Images are part of the proposal

Covers and inline figures are not decoration bolted on after approval. Generate or crop them into the private work tree, then register each change receipt. The proposal digest must include the managed asset references you intend to publish. Present crops and alt text with the prose when you ask for approval.

Do not promote on the strength of a successful image generation or a green build. Those events prove technical processing, not editorial permission.

Review means editorial complete, not publish

Marking work reviewed means factual checks, voice, links, and QA findings are addressed. It is not permission to write native content. Promotion requires a bound approval receipt that includes the exact proposalSha256 the reviewer saw, a decision of approve, and a short note. The agent must not invent that receipt.

If promotion fails hash checks, keep the approved tree unchanged and resolve the conflict from current source. Never hand-edit status JSON to force a publish.

Discard and recover without drama

Discard rejects active private work while preserving approved content. If a transaction is interrupted, use the recovery rollback path after inspecting affected files instead of deleting locks by hand. Shared approved assets are not automatically deleted when one article’s private work goes away.

Minimal operating loop

1. Create or begin a revision for a stable id.
2. Write the English body; remove scaffold markers; add internal links.
3. Register prose; run cover/illustration tools; register each receipt.
4. Export QA input, fix high findings, re-register if needed.
5. Mark reviewed; present the exact proposal digest to the owner.
6. Promote only with an approval file the owner authorized for that digest.

This loop is slower than pasting into docs/ directly. It is also how static editorial sites avoid silent overwrites and unverifiable “looks good” publishes.