view release on metacpan or  search on metacpan

README.md  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:

```sh
cpanm ASPEER::MakeMaker::Markdown::Publish
```

## GitHub Attestations

The release workflow generates [GitHub artifact attestations](https://docs.github.com/en/actions/concepts/security/artifact-attestations)
for distribution archives. Install the [GitHub CLI](https://cli.github.com/)
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:

```sh
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.

```perl
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:

```sh
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`:

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