ASPEER::MakeMaker::Markdown::Publish

Add MakeMaker targets for publishing Perl distribution documentation through MkDocs, VitePress, Docusaurus, or Astro Starlight.

The module is deliberately a thin adapter. It reads META_MERGE.x_documentation.publish from the live WriteMakefile arguments, encodes that configuration into the generated Makefile, and delegates every target to Markdown::Publish.

It also loads ASPEER::MakeMaker::Markdown::Pod, so one import supplies the doc and readme maintenance targets as well as the publication targets.

use ExtUtils::MakeMaker;
use ASPEER::MakeMaker::Markdown::Publish;

WriteMakefile(
    NAME         => 'Example',
    VERSION_FROM => 'lib/Example.pm',
    META_MERGE   => {
        'meta-spec' => {version => 2},
        x_documentation => {
            publish => {
                sources => ['doc'],
                name    => 'Example documentation',
            },
        },
    },
);

After regenerating the Makefile:

make doc
make publish_build
make publish_serve
# Update the local publication branch:
make publish_gh
# Update it and push that branch to origin:
make publish_gh-push
# Explicit Cloudflare Workers Static Assets deployment:
make publish_cloudflare

The same combined target set can be enabled without editing Makefile.PL:

perl -MASPEER::MakeMaker::Markdown::Publish Makefile.PL

MkDocs supplies all five targets when module is omitted. Set MARKDOWN_PUBLISH_MODULE to override the configured module at runtime. For generated engine configuration, the site name defaults to the WriteMakefile NAME; set x_documentation.publish.name for a friendlier title. An authored engine configuration keeps control of its own title. publish_gh builds and updates the local publication branch without contacting a remote. If x_documentation.publish.base is omitted, it derives /<repository>/ from origin, or / for an <owner>.github.io repository. Set it explicitly when the published URL uses another path. Generated VitePress, Docusaurus, and Starlight configuration receives this base; an authored engine configuration remains authoritative. Push the branch through the repository's normal Git workflow, or use publish_gh-push to update it and push only that branch to origin without forcing it. Set x_documentation.publish.config_extend to customise generated engine configuration without replacing it; it cannot be combined with config. publish_cloudflare builds and deploys the same site to the Worker named in an authored Wrangler config supplied as cloudflare => {config => 'wrangler.jsonc'} in x_documentation.publish. It neither commits nor pushes Git.

See the module documentation and examples.