ASPEER-MakeMaker-Markdown-Publish

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN


After regenerating the Makefile:

    make doc
    make publish_build
    make publish_serve
    # Update the local publication branch:
    make publish_gh
    # Update it and push that branch to origin:
    make publish_gh-push
    # Explicit Cloudflare Workers Static Assets deployment:
    make publish_cloudflare

The same combined target set can be enabled without editing Makefile.PL:

    perl -MASPEER::MakeMaker::Markdown::Publish Makefile.PL

MkDocs supplies all five targets when module is omitted. Set
MARKDOWN_PUBLISH_MODULE to override the configured module at runtime.
For generated engine configuration, the site name defaults to the
WriteMakefile NAME; set x_documentation.publish.name for a friendlier
title. An authored engine configuration keeps control of its own title.
publish_gh builds and updates the local publication branch without
contacting a remote. If x_documentation.publish.base is omitted, it
derives /<repository>/ from origin, or / for an <owner>.github.io
repository. Set it explicitly when the published URL uses another path.
Generated VitePress, Docusaurus, and Starlight configuration receives
this base; an authored engine configuration remains authoritative. Push
the branch through the repository's normal Git workflow, or use
publish_gh-push to update it and push only that branch to origin without
forcing it. Set x_documentation.publish.config_extend to customise

README  view on Meta::CPAN

x_documentation.publish only when the config lives elsewhere. The target
neither commits nor pushes 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 --assets option,
so this file does not need an assets.directory setting. Choose a unique
Worker name, authenticate Wrangler, regenerate the Makefile, and
publish:

    perl Makefile.PL
    make publish_cloudflare

See the module documentation and examples.

README.md  view on Meta::CPAN

After regenerating the Makefile:

```sh
make doc
make publish_build
make publish_serve
# Update the local publication branch:
make publish_gh
# Update it and push that branch to origin:
make publish_gh-push
# Explicit Cloudflare Workers Static Assets deployment:
make publish_cloudflare
```

The same combined target set can be enabled without editing `Makefile.PL`:

```sh
perl -MASPEER::MakeMaker::Markdown::Publish Makefile.PL
```

MkDocs supplies all five targets when `module` is omitted. Set
`MARKDOWN_PUBLISH_MODULE` to override the configured module at runtime.
For generated engine configuration, the site `name` defaults to the
`WriteMakefile` `NAME`; set `x_documentation.publish.name` for a friendlier
title. An authored engine configuration keeps control of its own title.
`publish_gh` builds and updates the local publication branch without contacting
a remote. If `x_documentation.publish.base` is omitted, it derives
`/<repository>/` from `origin`, or `/` for an `<owner>.github.io` repository.
Set it explicitly when the published URL uses another path. Generated
VitePress, Docusaurus, and Starlight configuration receives this base; an
authored engine configuration remains authoritative. Push the branch through
the repository's normal Git workflow, or use `publish_gh-push` to update it
and push only that branch to `origin` without forcing it.
Set `x_documentation.publish.config_extend` to customise generated engine

README.md  view on Meta::CPAN


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
this file does not need an `assets.directory` setting. Choose a unique Worker
name, authenticate Wrangler, regenerate the Makefile, and publish:

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

See the [module documentation](lib/ASPEER/MakeMaker/Markdown/Publish.pm.md) and
[examples](examples/README.md).

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

                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:

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

```text
doc
readme

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

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

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

                 sources => ['doc'],
                 config  => 'doc/mkdocs/mkdocs.yml',
             },
         },
     },
 );

=head1 DESCRIPTION

This is a thin MakeMaker adapter. It reads C<META_MERGE.x_documentation.publish>
from the live C<WriteMakefile> arguments and passes the settings to
C<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 C<ASPEER::MakeMaker::Markdown::Pod>, so the
generated Makefile includes its C<doc> and C<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 C<Makefile.PL> to discover it.


=head1 TARGETS


 doc

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

 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.

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

                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:

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

```text
doc
readme

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

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

t/01-targets.t  view on Meta::CPAN

is($config_hr->{'base'}, '/sample-docs/', 'publication base encoded');
is($config_hr->{'module'}, 'Markdown::Publish::MkDocs',
    'selected module encoded');
is($config_hr->{'config'}, 'doc/mkdocs/custom.yml',
    'MkDocs configuration location encoded');
is($config_hr->{'address'}, '127.0.0.1:8123',
    'MkDocs customization encoded');
is_deeply($config_hr->{'cloudflare'}, {config => 'doc/wrangler.jsonc'},
    'Cloudflare Worker configuration encoded');
ok(!exists($config_hr->{'name'}),
    'generated Makefile retains the user publication settings');


#  Execute generated targets through make and inspect the delegated calls
#
my $make=$Config{'make'} || 'make';
is(system($make, 'doc'), 0, 'generated documentation target succeeds');
like(slurp('lib/Sample.pm'), qr/^=head1 NAME$/m,
    'generated documentation target processes the sidecar');
is(system($^X, '-MASPEER::MakeMaker::Markdown::Publish', 'Makefile.PL'), 0,
    'Makefile regenerates after documentation updates VERSION_FROM');
is(system($make, 'publish_build'), 0, 'generated build target succeeds');
is(system($make, 'publish_serve'), 0, 'generated local server target delegates');
is(system($make, 'publish_gh'), 0,
    'generated local publication target delegates');
is(system($make, 'publish_gh-push'), 0,
    'generated publication push target delegates');
is(system($make, 'publish_cloudflare'), 0,
    'generated static-assets deployment target delegates');
my @target=map {decode_json($_)} grep {length($_)} split(/\n/, slurp('target.log'));
is_deeply(
    [map {$_->{'action'}} @target],
    ['build', 'serve', 'gh', 'gh-push', 'cloudflare'],
    'generated targets dispatch the selected action'
);
my $default_config_hr={%{$config_hr}, name => 'Sample'};
is_deeply($target[0]{'config'}, $default_config_hr,
    'distribution module name supplies the default site title');

t/01-targets.t  view on Meta::CPAN

#  Invalid custom metadata is rejected while generating the Makefile
#
my $invalid=slurp('Makefile.PL');
$invalid=~s/x_documentation\s*=>\s*\{/x_documentation => 'invalid', disabled => {/ ||
    die "unable to construct invalid metadata fixture";
blurp('Makefile.PL', $invalid);
isnt(system($^X, '-MASPEER::MakeMaker::Markdown::Publish', 'Makefile.PL'), 0,
    'invalid x_documentation metadata rejected');


#  Publication targets work when MakeMaker metadata supplies no settings
#
blurp('Makefile.PL', <<'MAKEFILE_PL');
use strict;
use warnings;
use ExtUtils::MakeMaker;
WriteMakefile(
    NAME         => 'Sample',
    VERSION_FROM => 'lib/Sample.pm',
);
MAKEFILE_PL



( run in 1.269 second using v1.01-cache-2.11-cpan-234fa220139 )