Markdown::Publish

Appearance

Workflow ​

It helps to separate documentation maintenance from site assembly and publication. They are related, but they do not have the same side effects.

  1. make doc, supplied by ASPEER::MakeMaker::Markdown::Pod, converts maintained DocBook articles to Markdown and merges Markdown sidecars into Perl sources as POD documentation.

  2. A build or preview directs Markdown::Publish to copy the selected Markdown and assets into a temporary assembly, create navigation, and invoke the chosen site generator.

  3. A publication action pushes the completed site somewhere else. GitHub publication updates the "gh-pages" branch; Cloudflare publication invokes Wrangler to push as a Pages site.

INFO

The publisher step expects Markdown. DocBook is an authoring format in the wider toolchain, bit is not understood directly by the site backends. Run make doc after changing an XML article so that its sibling Markdown is current before building the site.