view release on metacpan or search on metacpan
examples/basic/README.md view on Meta::CPAN
# Basic publishing targets
This example publishes only Markdown beneath `doc/` and uses the generated
MkDocs configuration. Generate its Makefile with `perl Makefile.PL`, then run
`make doc`, `make publish_build`, or `make publish_serve`. Importing the
publication adapter supplies both the documentation-maintenance and publication
targets.
MkDocs is selected because no `module` is configured. Set
`MARKDOWN_PUBLISH_MODULE` to try another installed engine without
regenerating the Makefile.
lib/ASPEER/MakeMaker/Markdown/Publish.pm view on Meta::CPAN
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
lib/ASPEER/MakeMaker/Markdown/Publish.pm view on Meta::CPAN
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:
```jsonc
{
"name": "example-documentation",
"compatibility_date": "2026-09-29"
lib/ASPEER/MakeMaker/Markdown/Publish.pm view on Meta::CPAN
from the live C<WriteMakefile> arguments and passes the settings to
C<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 C<ASPEER::MakeMaker::Markdown::Pod>, so the
generated Makefile includes its C<doc> and C<readme> maintenance targets alongside
the publication targets. The equivalent command-line activation is:
perl -MASPEER::MakeMaker::Markdown::Publish Makefile.PL
The selected C<module> is one of C<Markdown::Publish::MkDocs>,
C<::VitePress>, C<::Docusaurus>, or C<::Starlight>. One engine is active at a
time. Its C<config> and other engine-specific options are top-level values
in the C<publish> hash. Alternatively, set only C<config_file> to a JSON file
containing the selected C<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 C<Makefile.PL> to discover it.
=head1 TARGETS
doc
readme
publish_build
publish_serve
publish_gh
publish_gh-push
publish_cloudflare
C<publish_build> prepares and renders the site. C<publish_serve> starts the
selected engine's foreground local server. C<publish_gh> builds, updates the
local publication branch, and does not contact a remote. C<publish_gh-push>
performs the same operation, then pushes only that branch to C<origin> without
forcing it. C<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.
=head1 CONFIGURATION
MkDocs is used when C<module> is omitted. Set C<module> in
C<META_MERGE.x_documentation.publish> to select another engine, or set
C<MARKDOWN_PUBLISH_MODULE> to override it at runtime.
Without C<sources>, an existing C<doc/> is the publication boundary. Only when
C<doc/> is absent are module and executable sidecars the default. An explicit
C<sources> list is exact. C<output>, C<name>, C<base>, and C<branch> are common settings;
see the selected engine module for its own options. For generated engine
configuration, C<name> defaults to the C<NAME> supplied to C<WriteMakefile>. Set
it explicitly for a friendlier site title:
publish => {
name => 'Example documentation',
},
An external C<config_file> or an authored engine configuration remains
authoritative for its own site title.
lib/ASPEER/MakeMaker/Markdown/Publish.pm view on Meta::CPAN
C<publish_gh> derives C<<< /<repository>/ >>> from the C<origin> repository name, or
uses C</> for an C<<< <owner>.github.io >>> repository. The inferred value applies
only to the GitHub Pages build. Set C<base> explicitly when the published URL
uses a different path; authored engine configuration remains authoritative.
publish => {
module => 'Markdown::Publish::VitePress',
base => '/example/',
},
Set C<config_extend> to customise the selected engine's generated configuration
without replacing it. It is passed unchanged to C<Markdown::Publish> and
cannot be combined with C<config>. MkDocs accepts supplemental YAML; the Node
publishers accept the extension functions documented by their engine modules.
For Workers Static Assets, place C<wrangler.jsonc> or C<wrangler.json> in the
project root. C<publish_cloudflare> discovers those names in that order, so no
Cloudflare publication metadata is needed for the usual layout. Set
C<<< cloudflare => {config => 'deploy/wrangler.docs.jsonc'} >>> inside C<publish> to
select a file elsewhere. Optionally set C<wrangler> to the executable path or
C<environment> to an authored Wrangler environment in the same C<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 C<wrangler.jsonc> is:
{
"name": "example-documentation",
"compatibility_date": "2026-09-29"
lib/ASPEER/MakeMaker/Markdown/Publish.pm.md view on Meta::CPAN
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
lib/ASPEER/MakeMaker/Markdown/Publish.pm.md view on Meta::CPAN
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:
```jsonc
{
"name": "example-documentation",
"compatibility_date": "2026-09-29"
lib/ASPEER/MakeMaker/Markdown/Publish/MM.pm view on Meta::CPAN
Calls the shared `ASPEER::MakeMaker` `const_config` implementation, validates
the `x_documentation` metadata shape, and stores the JSON publication hash as a
Makefile-safe Base64 value.
## publish
Decodes the configuration passed by the generated target. When inline
configuration does not contain `name`, it uses the MakeMaker `NAME` as the
default site title. An external `config_file` remains authoritative. The method
then constructs `Markdown::Publish` and invokes the requested action on
the selected backend class.
# SEE ALSO
`ASPEER::MakeMaker::Markdown::Publish`, `Markdown::Publish`
# AUTHOR
Andrew Speer <andrew.speer@isolutions.com.au>
# LICENSE and COPYRIGHT
lib/ASPEER/MakeMaker/Markdown/Publish/MM.pm view on Meta::CPAN
the C<x_documentation> metadata shape, and stores the JSON publication hash as a
Makefile-safe Base64 value.
=head2 publish
Decodes the configuration passed by the generated target. When inline
configuration does not contain C<name>, it uses the MakeMaker C<NAME> as the
default site title. An external C<config_file> remains authoritative. The method
then constructs C<Markdown::Publish> and invokes the requested action on
the selected backend class.
=head1 SEE ALSO
C<ASPEER::MakeMaker::Markdown::Publish>, C<Markdown::Publish>
=head1 AUTHOR
Andrew Speer L<mailto:andrew.speer@isolutions.com.au>
lib/ASPEER/MakeMaker/Markdown/Publish/MM.pm.md view on Meta::CPAN
Calls the shared `ASPEER::MakeMaker` `const_config` implementation, validates
the `x_documentation` metadata shape, and stores the JSON publication hash as a
Makefile-safe Base64 value.
## publish
Decodes the configuration passed by the generated target. When inline
configuration does not contain `name`, it uses the MakeMaker `NAME` as the
default site title. An external `config_file` remains authoritative. The method
then constructs `Markdown::Publish` and invokes the requested action on
the selected backend class.
# SEE ALSO
`ASPEER::MakeMaker::Markdown::Publish`, `Markdown::Publish`
# AUTHOR
Andrew Speer <andrew.speer@isolutions.com.au>
# LICENSE AND COPYRIGHT
t/01-targets.t view on Meta::CPAN
# Decode the private macro to prove values came from live META_MERGE input
#
my ($encoded)=$makefile=~/^PUBLISH_CONFIG\s*=\s*(\S+)$/m;
ok(defined($encoded) && length($encoded), 'publication configuration macro generated');
my $config_hr=decode_json(decode_base64($encoded));
is_deeply($config_hr->{'sources'}, ['doc'], 'source directories encoded');
is($config_hr->{'base'}, '/sample-docs/', 'publication base encoded');
is($config_hr->{'module'}, 'Markdown::Publish::MkDocs',
'selected module encoded');
is($config_hr->{'config'}, 'doc/mkdocs/custom.yml',
'MkDocs configuration location encoded');
is($config_hr->{'address'}, '127.0.0.1:8123',
'MkDocs customization encoded');
is_deeply($config_hr->{'cloudflare'}, {config => 'doc/wrangler.jsonc'},
'Cloudflare Worker configuration encoded');
ok(!exists($config_hr->{'name'}),
'generated Makefile retains the user publication settings');
t/01-targets.t view on Meta::CPAN
is(system($make, 'publish_gh'), 0,
'generated local publication target delegates');
is(system($make, 'publish_gh-push'), 0,
'generated publication push target delegates');
is(system($make, 'publish_cloudflare'), 0,
'generated static-assets deployment target delegates');
my @target=map {decode_json($_)} grep {length($_)} split(/\n/, slurp('target.log'));
is_deeply(
[map {$_->{'action'}} @target],
['build', 'serve', 'gh', 'gh-push', 'cloudflare'],
'generated targets dispatch the selected action'
);
my $default_config_hr={%{$config_hr}, name => 'Sample'};
is_deeply($target[0]{'config'}, $default_config_hr,
'distribution module name supplies the default site title');
# An explicit publication name overrides the distribution module name
#
my $configured=slurp('Makefile.PL');
$configured=~s/(publish\s*=>\s*\{\n)/$1 name => 'Sample documentation',\n/ ||