Markdown::Publish

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

Install and run

Install this distribution with cpanm ., then install the external site
generator required for the backend you use.

    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.