A practical documentation cycle

A maintainable workflow keeps authored material, generated Markdown, site output, and remote publication distinct.

1. Edit DocBook articles, Markdown articles, and source sidecars.

2. Run make doc and review the generated Markdown and POD changes.

3. Run make publish_serve and inspect navigation, links, code blocks, images, and the home page.

4. Run make publish_build so strict or production-only build failures appear before publication.

5. Commit the authored and durable generated documentation through the project's normal source-control workflow.

6. Run make publish_gh and inspect the local branch, or run an explicitly authorised remote publication action.

Site assembly happens in temporary directories, while the rendered output uses site/ by default. Keep generated site output out of the source branch unless the project has a specific reason to track it. The publication branch is the durable Git representation of that output.