ASPEER::MakeMaker::Markdown::Publish

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

Installation

Install the released distribution and its prerequisites from CPAN:

    cpanm ASPEER::MakeMaker::Markdown::Publish

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
ASPEER-MakeMaker-Markdown-Publish-VERSION.tar.gz from MetaCPAN or a CPAN
mirror, replace VERSION, and run:

    gh attestation verify ASPEER-MakeMaker-Markdown-Publish-VERSION.tar.gz --repo aspeer/pm-ASPEER-MakeMaker-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.

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 wrangler.jsonc, or wrangler.json as a
fallback, in the project root. Set
cloudflare => {config => 'deploy/wrangler.docs.jsonc'} in
x_documentation.publish only when the config lives elsewhere. The target
neither commits nor pushes Git.

A minimal project-root wrangler.jsonc is:

    {
      "name": "example-documentation",
      "compatibility_date": "2026-09-29"
    }

The target supplies the generated site using Wrangler's --assets option,
so this file does not need an assets.directory setting. Choose a unique
Worker name, authenticate Wrangler, regenerate the Makefile, and
publish:

    perl Makefile.PL
    make publish_cloudflare

See the module documentation and examples.