/ 
Markdown-Publish-1.004
/ README.md

Markdown::Publish

Build, preview, and publish Markdown documentation from Perl distribution trees with MkDocs, VitePress, Docusaurus, or Astro Starlight.

Installation

Install the released distribution and its prerequisites from CPAN:

cpanm Markdown::Publish

Install the external site generator required for the backend you use.

GitHub Attestations

The release workflow generates GitHub artifact attestations for distribution archives. Install the GitHub CLI with gh attestation support and authenticate with gh auth login.

To verify a CPAN release archive separately, download Markdown-Publish-VERSION.tar.gz from MetaCPAN or a CPAN mirror, replace VERSION, and run:

gh attestation verify Markdown-Publish-VERSION.tar.gz --repo aspeer/pm-Markdown-Publish

A successful verification confirms that the archive checksum matches an attestation from this repository. The workflow publishes the same archive to GitHub Releases and CPAN. Older releases and GitHub's automatically generated source-code archives are not covered.

Run

markdown-publish build
markdown-publish serve
# Update the local publication branch:
markdown-publish gh
# Update it and push that branch to origin:
markdown-publish gh-push
# Explicit Cloudflare Workers Static Assets deployment:
markdown-publish cloudflare --config doc/project.json

An existing doc/ directory is the default publication boundary. During site assembly, Markdown under lib/ and bin/ is copied into temporary lib/ and bin/ directories beside the guide, preserving its relative path and filename. For example, a guide can link to lib/Example/Module.pm.md. Nothing is copied into the repository's doc/ directory. Mirrored pages are available through links but are not added to generated navigation. When doc/ is absent, sidecars become the default source pages; an explicit source list can also select them using the existing modules/ and utilities/ layout. Guides with multiple top-level headings are split into stable ID-based pages. Nested Markdown under doc/ is available through links but is not split or added to generated navigation. For each engine, the first top-level page becomes the home page when no index.md was authored; its original URL remains available for links.

MkDocs is the default engine. Select another with module in doc/project.json or with --module. MARKDOWN_PUBLISH_MODULE overrides either selection when set. The mkdocs, vitepress, docusaurus, and starlight shortcuts select the bundled publishers. A fully qualified class name may select another installed Markdown::Publish subclass. For example, MARKDOWN_PUBLISH_MODULE=docusaurus make publish_serve. The constants in Markdown::Publish::Constant may also be overridden by matching environment variables or an adjacent Constant.pm.local file. Settings include source directories, engine configuration path, output directory, publication branch, deployment base, and executable names. For generated VitePress, Docusaurus, and Starlight configuration, base maps to the engine's deployment base path; an authored engine configuration remains authoritative. Set config_extend to customise generated defaults without replacing them. MkDocs inherits the supplied YAML; the Node publishers call an extension function with their generated configuration and publication context. It cannot be combined with the authoritative config setting. See the engine module documentation for its extension-module shape. For npm-based engines, installation start and completion are always reported. Set MARKDOWN_PUBLISH_NPM_VERBOSE=1 to show npm's installation output as well. To listen on another interface and port with any publisher, run MARKDOWN_PUBLISH_HOST=0.0.0.0 MARKDOWN_PUBLISH_PORT=8002 make publish_serve. Without these settings, each publisher keeps its existing local server address.

The HTML output defaults to site/. gh requires an existing Git commit and configured author identity. It updates the local gh-pages branch through a temporary worktree without contacting a remote. Push that branch through the repository's normal Git workflow when it is ready. If base is not configured, gh derives /<repository>/ from origin, or / for an <owner>.github.io repository. Set base explicitly when the published URL uses a different path. gh-push performs the same local publication and then pushes only the publication branch to origin without forcing it.

For Workers Static Assets, set cloudflare.config in doc/project.json to a dedicated Wrangler configuration file. The cloudflare action builds the selected engine and deploys its site directory with Wrangler; it neither commits nor pushes Git. Wrangler's existing login or environment supplies authentication.

See API details and examples. Each engine has its own module under Markdown::Publish.

ASPEER::MakeMaker::Markdown::Publish supplies equivalent Makefile targets and passes the META_MERGE.x_documentation.publish field to this module.