ASPEER-MakeMaker-Markdown-Publish
view release on metacpan or search on metacpan
Preamble
The license agreements of most software companies try to keep users
at the mercy of those companies. By contrast, our General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. The
General Public License applies to the Free Software Foundation's
software and to any other program whose authors commit to using it.
You can use it for your programs, too.
When we speak of free software, we are referring to freedom, not
price. Specifically, the General Public License is designed to make
sure that you have the freedom to give away or sell copies of free
software, that you receive source code or can get it if you want it,
that you can change the software or use pieces of it in new free
programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
Program or a portion of it, either verbatim or with modifications. Each
licensee is addressed as "you".
1. You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer to this
General Public License and to the absence of any warranty; and give any
other recipients of the Program a copy of this General Public License
along with the Program. You may charge a fee for the physical act of
transferring a copy.
2. You may modify your copy or copies of the Program or any portion of
it, and copy and distribute such modifications under the terms of Paragraph
1 above, provided that you also do the following:
a) cause the modified files to carry prominent notices stating that
you changed the files and the date of any change; and
b) cause the whole of any work that you distribute or publish, that
in whole or in part contains the Program or any part thereof, either
c) If the modified program normally reads commands interactively when
run, you must cause it, when started running for such interactive use
in the simplest and most usual way, to print or display an
announcement including an appropriate copyright notice and a notice
that there is no warranty (or else, saying that you provide a
warranty) and that users may redistribute the program under these
conditions, and telling the user how to view a copy of this General
Public License.
d) You may charge a fee for the physical act of transferring a
copy, and you may at your option offer warranty protection in
exchange for a fee.
Mere aggregation of another independent work with the Program (or its
derivative) on a volume of a storage or distribution medium does not bring
the other work under the scope of these terms.
3. You may copy and distribute the Program (or a portion or derivative of
it, under Paragraph 2) in object code or executable form under the terms of
Paragraphs 1 and 2 above provided that you also do one of the following:
years, to give any third party free (except for a nominal charge
for the cost of distribution) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,
c) accompany it with the information you received as to where the
corresponding source code may be obtained. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)
Source code for a work means the preferred form of the work for making
modifications to it. For an executable file, complete source code means
all the source code for all modules it contains; but, as a special
exception, it need not include source code for modules which are standard
libraries that accompany the operating system on which the executable
file runs, or for standard header files or definitions files that
accompany that operating system.
4. You may not copy, modify, sublicense, distribute or transfer the
Program except as expressly provided under this General Public License.
Any attempt otherwise to copy, modify, sublicense, distribute or transfer
# 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
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
lib/ASPEER/MakeMaker/Markdown/Publish.pm view on Meta::CPAN
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/',
},
```
lib/ASPEER/MakeMaker/Markdown/Publish.pm view on Meta::CPAN
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
lib/ASPEER/MakeMaker/Markdown/Publish.pm.md view on Meta::CPAN
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/',
},
```
t/01-targets.t view on Meta::CPAN
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');
# An explicit publication name overrides the distribution module name
#
my $configured=slurp('Makefile.PL');
$configured=~s/(publish\s*=>\s*\{\n)/$1 name => 'Sample documentation',\n/ ||
die "unable to construct named publication fixture";
blurp('Makefile.PL', $configured);
is(system($^X, '-MASPEER::MakeMaker::Markdown::Publish', 'Makefile.PL'), 0,
'Makefile.PL accepts an explicit publication name');
is(system($make, 'publish_build'), 0,
'generated build target accepts the explicit publication name');
@target=map {decode_json($_)} grep {length($_)} split(/\n/, slurp('target.log'));
is($target[-1]{'config'}{'name'}, 'Sample documentation',
'explicit publication name overrides the default');
# Explicit and composed Pod imports remain idempotent
#
my $explicit=slurp('Makefile.PL');
$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');
( run in 2.807 seconds using v1.01-cache-2.11-cpan-10df4c37326 )