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

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:

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.

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