NAME

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

SYNOPSIS

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:

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 Makefile.PL to discover it.

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.

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:

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

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, set cloudflare => {config => 'wrangler.jsonc'} inside publish. This path selects a dedicated Worker configuration with its name and compatibility date. 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.

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 mailto:andrew.speer@isolutions.com.au

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.