view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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