ASPEER-MakeMaker-Markdown-Publish

 view release on metacpan or  search on metacpan

CONTRIBUTING.md  view on Meta::CPAN

# Contributing to ASPEER::MakeMaker::Markdown::Publish

Bug reports and focused contributions are welcome. Search the
[GitHub issues](https://github.com/aspeer/pm-ASPEER-MakeMaker-Markdown-Publish/issues)
before opening a new one, and include a minimal reproduction where possible.

Fork the [GitHub repository](https://github.com/aspeer/pm-ASPEER-MakeMaker-Markdown-Publish),
create a topic branch, keep changes focused, and submit a GitHub pull request.
Run `perl Makefile.PL`, `make test`, and `make disttest` before submitting.

Do not include credentials or private data. Report potential vulnerabilities
privately as described in [SECURITY.md](SECURITY.md).

Changes  view on Meta::CPAN

Revision history for ASPEER-MakeMaker-Markdown-Publish

1.004  2026-09-29

    - Document metadata-free Cloudflare publication through a project-root
      wrangler.jsonc or wrangler.json file.
    - Require Markdown::Publish 1.004 and verify that publish_cloudflare
      delegates correctly when publication metadata is omitted.

1.003  2026-09-26

    - Publish public repository metadata through the GitHub mirror.
    - Add contributor and security policies, dependency auditing and
      artifact-attestation verification guidance.
    - Declare the CPAN authority in distribution metadata.

1.002  2026-09-26

    - Initial release.
    - Add MakeMaker targets for each supported publishing backend.
    - Pass x_documentation publishing configuration to the reusable engine.
    - Load ASPEER::MakeMaker::Markdown::Pod so publication-enabled
      Makefile.PL files also receive the local documentation targets.
    - Derive the default site title from WriteMakefile metadata.
    - Add local GitHub Pages branch preparation and explicit push targets.
    - Install pandoc in GitHub Actions for documentation integration tests.

MANIFEST  view on Meta::CPAN

lib/ASPEER/MakeMaker/Markdown/Publish/MM/postamble.inc
LICENSE
Makefile.PL
MANIFEST			This list of files
MANIFEST.SKIP
README
README.md
SECURITY.md
t/00-load.t
t/01-targets.t
META.yml                                 Module YAML meta-data (added by MakeMaker)
META.json                                Module JSON meta-data (added by MakeMaker)

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

},
```

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"
}
```

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

     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

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

},
```

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"
}
```

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

    $publish_hr={} unless defined($publish_hr);
    $mm_or->{'macro'}{'PUBLISH_CONFIG'}=encode_base64(encode_json($publish_hr), '');
    return $const_config;

}


sub publish {


    #  Decode the Makefile-safe metadata payload and delegate the requested
    #  action without re-running Makefile.PL.
    #
    my ($self, $param_hr)=(shift(), arg(@_));
    my ($encoded, $action)=@{$param_hr->{'ARGV_AR'}};
    die "publication configuration unavailable\n"
        unless defined($encoded) && length($encoded);
    my $publish_hr=decode_json(decode_base64($encoded));
    die "publication configuration must decode to a hash reference\n"
        unless ref($publish_hr) eq 'HASH';
    if (!exists($publish_hr->{'name'}) &&

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

This class implements the MakeMaker-specific portion of
`ASPEER::MakeMaker::Markdown::Publish`. It inherits the common MakeMaker helper,
encodes `META_MERGE.x_documentation.publish` into a private Makefile macro, and
delegates generated targets to `Markdown::Publish`.

# METHODS

## const_config

Calls the shared `ASPEER::MakeMaker` `const_config` implementation, validates
the `x_documentation` metadata shape, and stores the JSON publication hash as a
Makefile-safe Base64 value.

## publish

Decodes the configuration passed by the generated target. When inline
configuration does not contain `name`, it uses the MakeMaker `NAME` as the
default site title. An external `config_file` remains authoritative. The method
then constructs `Markdown::Publish` and invokes the requested action on
the selected backend class.

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

encodes C<META_MERGE.x_documentation.publish> into a private Makefile macro, and
delegates generated targets to C<Markdown::Publish>.


=head1 METHODS


=head2 const_config

Calls the shared C<ASPEER::MakeMaker> C<const_config> implementation, validates
the C<x_documentation> metadata shape, and stores the JSON publication hash as a
Makefile-safe Base64 value.


=head2 publish

Decodes the configuration passed by the generated target. When inline
configuration does not contain C<name>, it uses the MakeMaker C<NAME> as the
default site title. An external C<config_file> remains authoritative. The method
then constructs C<Markdown::Publish> and invokes the requested action on
the selected backend class.

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

This class implements the MakeMaker-specific portion of
`ASPEER::MakeMaker::Markdown::Publish`. It inherits the common MakeMaker helper,
encodes `META_MERGE.x_documentation.publish` into a private Makefile macro, and
delegates generated targets to `Markdown::Publish`.

# METHODS

## const_config

Calls the shared `ASPEER::MakeMaker` `const_config` implementation, validates
the `x_documentation` metadata shape, and stores the JSON publication hash as a
Makefile-safe Base64 value.

## publish

Decodes the configuration passed by the generated target. When inline
configuration does not contain `name`, it uses the MakeMaker `NAME` as the
default site title. An external `config_file` remains authoritative. The method
then constructs `Markdown::Publish` and invokes the requested action on
the selected backend class.

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

$explicit=~s/(use ExtUtils::MakeMaker;\n)/$1use ASPEER::MakeMaker::Markdown::Pod;\n/ ||
    die "unable to construct explicit Pod import fixture";
blurp('Makefile.PL', $explicit);
is(system($^X, '-MASPEER::MakeMaker::Markdown::Publish', 'Makefile.PL'), 0,
    'explicit Pod and command-line publication imports succeed together');
$makefile=slurp('Makefile');
@doc_target=($makefile=~/^doc :: readme$/mg);
is(scalar(@doc_target), 1, 'combined imports generate one doc target');


#  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
is(system($^X, '-MASPEER::MakeMaker::Markdown::Publish', 'Makefile.PL'), 0,
    'Makefile.PL accepts omitted publication metadata');
is(system($make, 'publish_cloudflare'), 0,
    'Cloudflare target delegates without publication metadata');
@target=map {decode_json($_)} grep {length($_)} split(/\n/, slurp('target.log'));
is_deeply($target[-1]{'config'}, {name => 'Sample'},
    'Cloudflare target passes only the default distribution name');

chdir($cwd) || die "unable to restore cwd $cwd: $!";
done_testing();