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

{
    "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

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.