view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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

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:

```jsonc
{
  "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:

```sh
perl Makefile.PL
make publish_cloudflare
```

See the [module documentation](lib/ASPEER/MakeMaker/Markdown/Publish.pm.md) and
[examples](examples/README.md).