When something does not look right

• The site title is “Documentation”

  Set name. MakeMaker normally derives it from NAME, but standalone configurations need their own friendly name.

• GitHub Pages has missing styles or broken links

  Check base. Leave it unset for normal repository-name inference, or set the exact path explicitly when the published URL differs.

• A module sidecar is missing from navigation

  This is expected when doc/ exists. Sidecars are mirrored for links, while top-level project articles form generated navigation. Name lib/ explicitly as a source if those pages should become the primary publication.

• An XML edit is absent from the site

  Run make doc. The publisher reads the sibling Markdown generated from the DocBook source.

• A custom config loses generated navigation

  Use config_extend when you want to supplement generated defaults. A config file is intentionally authoritative.

• The wrong engine runs

  Check MARKDOWN_PUBLISH_MODULE first because it overrides metadata and JSON configuration. Then check the module value in the active configuration source.

• An npm installation fails without enough detail

  Set MARKDOWN_PUBLISH_NPM_VERBOSE=1 and repeat the build to see normal npm output.