view release on metacpan or  search on metacpan

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

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:

```jsonc
{
    "name": "example-documentation",
    "compatibility_date": "2026-09-29"
}
```

The target supplies the generated site using Wrangler's `--assets` option, so
the file does not need an `assets.directory` setting. Choose a unique Worker
name, authenticate Wrangler, regenerate the Makefile, and run:

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

# ERRORS

`x_documentation` and `x_documentation.publish` must be hash references when
supplied. Invalid configuration and failed target actions are fatal.

# SEE ALSO

`Markdown::Publish`, `ASPEER::MakeMaker::Markdown::Pod`

# AUTHOR

Andrew Speer <andrew.speer@isolutions.com.au>

# LICENSE and COPYRIGHT

This file is part of ASPEER::MakeMaker::Markdown::Publish.

This software is copyright (c) 2026 by Andrew Speer <andrew.speer@isolutions.com.au>.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

Full license text is available at:

<http://dev.perl.org/licenses/>


=end markdown


=head1 NAME

ASPEER::MakeMaker::Markdown::Publish - MakeMaker targets for Markdown publication


=head1 SYNOPSIS


 use ExtUtils::MakeMaker;
 use ASPEER::MakeMaker::Markdown::Publish;

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

=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.

For generated VitePress, Docusaurus, and Starlight configuration, C<base> sets
the deployment path and must begin and end with C</>. When it is omitted,
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"
 }
The target supplies the generated site using Wrangler's C<--assets> option, so
the file does not need an C<assets.directory> setting. Choose a unique Worker
name, authenticate Wrangler, regenerate the Makefile, and run:


 perl Makefile.PL
 make publish_cloudflare

=head1 ERRORS

C<x_documentation> and C<x_documentation.publish> must be hash references when
supplied. Invalid configuration and failed target actions are fatal.


=head1 SEE ALSO

C<Markdown::Publish>, C<ASPEER::MakeMaker::Markdown::Pod>


=head1 AUTHOR

Andrew Speer L<mailto:andrew.speer@isolutions.com.au>


=head1 LICENSE AND COPYRIGHT

This file is part of ASPEER::MakeMaker::Markdown::Publish. Copyright (c) 2026
Andrew Speer. This is free software; you can redistribute it and/or modify it
under the same terms as Perl 5.

=cut