Task::Markdown::Publish

Task::Markdown::Publish installs the complete documentation conversion and publishing toolchain for Perl distributions. It contains everything installed by Task::Markdown::Pod, plus the reusable site publisher and the MakeMaker targets for building, previewing, and publishing documentation.

Installation

Install the released bundle and its Perl prerequisites from CPAN:

cpanm Task::Markdown::Publish

The bundle installs:

• Task::Markdown::Pod, Markdown::Pod::Embed, Docbook::Convert, and ASPEER::MakeMaker::Markdown::Pod for conversion and maintenance;
• Markdown::Publish for MkDocs, VitePress, Docusaurus, and Astro Starlight site operations;
• ASPEER::MakeMaker::Markdown::Publish for publish_build, publish_serve, publish_gh, publish_gh-push, and publish_cloudflare MakeMaker targets.

System prerequisites

CPAN installs Perl modules only. On Fedora, install the conversion and basic build prerequisites with:

sudo dnf install perl perl-App-cpanminus perl-devel make gcc expat-devel \
  pandoc libxml2 libxslt git

The default MkDocs backend additionally needs Python and MkDocs Material:

sudo dnf install python3-pip
python3 -m pip install --user mkdocs-material

VitePress, Docusaurus, and Astro Starlight need Node.js and npm. Their project packages are installed into temporary build directories by Markdown::Publish:

sudo dnf install nodejs npm

Cloudflare publication needs Wrangler and an authenticated account. Install it only when that explicit deployment target is required:

npm install --global wrangler
wrangler login

Pandoc is used for DocBook conversion and README generation; xmllint and xsltproc are supplied by Fedora's libxml2 and libxslt packages. Git is needed only for gh/gh-push publication branch operations. No Task module creates accounts, authenticates tools, pushes Git branches, or deploys sites.

Use

Enable the complete MakeMaker target set:

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

WriteMakefile(
    NAME         => 'My::Module',
    VERSION_FROM => 'lib/My/Module.pm',
    META_MERGE   => {
        'meta-spec' => {version => 2},
        x_documentation => {
            publish => {
                module  => 'mkdocs',
                sources => ['doc'],
            },
        },
    },
);

Then run the local workflows explicitly:

perl Makefile.PL
make doc
make publish_build
make publish_serve

The standalone publisher provides the same site operations without MakeMaker:

markdown-publish build
markdown-publish serve

Publication branch updates and Cloudflare deployment remain separate, explicit operations. See the Markdown::Publish documentation before using them.

GitHub attestations

Tagged releases build one distribution archive, publish it to GitHub Releases and CPAN, and attach GitHub provenance and a Sigstore bundle. After downloading Task-Markdown-Publish-VERSION.tar.gz from CPAN, verify its attestation with:

gh attestation verify Task-Markdown-Publish-VERSION.tar.gz \
  --repo aspeer/pm-Task-Markdown-Publish

Author

Andrew Speer andrew.speer@isolutions.com.au

License and copyright

This software is copyright (c) 2026 by Andrew Speer. It may be distributed under the same terms as Perl itself.