ASPEER-MakeMaker-Markdown-Publish

 view release on metacpan or  search on metacpan

lib/ASPEER/MakeMaker/Markdown/Publish.pm.md  view on Meta::CPAN


# SYNOPSIS

```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 => {
                module  => 'Markdown::Publish::MkDocs',
                sources => ['doc'],
                config  => 'doc/mkdocs/mkdocs.yml',
            },
        },
    },
);
```

# DESCRIPTION

This is a thin MakeMaker adapter. It reads `META_MERGE.x_documentation.publish`
from the live `WriteMakefile` arguments and passes the settings to
`Markdown::Publish` when a target is invoked. It does not assemble
documents, run a publishing engine, or update Git itself.

Importing this module also imports `ASPEER::MakeMaker::Markdown::Pod`, so the
generated Makefile includes its `doc` and `readme` maintenance targets alongside
the publication targets. The equivalent command-line activation is:

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

The selected `module` is one of `Markdown::Publish::MkDocs`,
`::VitePress`, `::Docusaurus`, or `::Starlight`. One engine is active at a
time. Its `config` and other engine-specific options are top-level values
in the `publish` hash. Alternatively, set only `config_file` to a JSON file
containing the selected `module` and settings. That file is read when the
target runs, so edits do not require a regenerated Makefile.

Configuration supplied inline is encoded into the generated Makefile. The
targets do not re-run `Makefile.PL` to discover it.

# TARGETS

```text
doc
readme
publish_build
publish_serve
publish_gh
publish_gh-push
publish_cloudflare
```

`publish_build` prepares and renders the site. `publish_serve` starts the
selected engine's foreground local server. `publish_gh` builds, updates the
local publication branch, and does not contact a remote. `publish_gh-push`
performs the same operation, then pushes only that branch to `origin` without
forcing it. `publish_cloudflare`
builds and deploys the same site as Workers Static Assets using an authored
Wrangler configuration. Git branch publication and Cloudflare deployment are
independent; neither calls the other.

# CONFIGURATION

MkDocs is used when `module` is omitted. Set `module` in
`META_MERGE.x_documentation.publish` to select another engine, or set
`MARKDOWN_PUBLISH_MODULE` to override it at runtime.

Without `sources`, an existing `doc/` is the publication boundary. Only when
`doc/` is absent are module and executable sidecars the default. An explicit
`sources` list is exact. `output`, `name`, `base`, and `branch` are common settings;
see the selected engine module for its own options. For generated engine
configuration, `name` defaults to the `NAME` supplied to `WriteMakefile`. Set
it explicitly for a friendlier site title:

```perl
publish => {
    name => 'Example documentation',
},
```

An external `config_file` or an authored engine configuration remains
authoritative for its own site title.

For generated VitePress, Docusaurus, and Starlight configuration, `base` sets
the deployment path and must begin and end with `/`. When it is omitted,
`publish_gh` derives `/<repository>/` from the `origin` repository name, or
uses `/` for an `<owner>.github.io` repository. The inferred value applies
only to the GitHub Pages build. Set `base` explicitly when the published URL
uses a different path; authored engine configuration remains authoritative.

```perl
publish => {
    module => 'Markdown::Publish::VitePress',
    base   => '/example/',
},
```

Set `config_extend` to customise the selected engine's generated configuration
without replacing it. It is passed unchanged to `Markdown::Publish` and
cannot be combined with `config`. MkDocs accepts supplemental YAML; the Node
publishers accept the extension functions documented by their engine modules.

For Workers Static Assets, place `wrangler.jsonc` or `wrangler.json` in the
project root. `publish_cloudflare` discovers those names in that order, so no
Cloudflare publication metadata is needed for the usual layout. Set
`cloudflare => {config => 'deploy/wrangler.docs.jsonc'}` inside `publish` to
select a file elsewhere. Optionally set `wrangler` to the executable path or
`environment` to an authored Wrangler environment in the same `cloudflare`
hash. Wrangler uses its own login or environment for authentication; do not
put credentials in metadata. Deployment does not change Git.

A minimal project-root `wrangler.jsonc` is:



( run in 0.770 second using v1.01-cache-2.11-cpan-234fa220139 )