view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME

ASPEER::MakeMaker::Markdown::Pod - keep Perl documentation in Markdown
and ship it as POD

GITHUB ATTESTATIONS

The release workflow generates GitHub artifact attestations for
distribution archives. Install the GitHub CLI with gh attestation
support and authenticate with gh auth login.

Download ASPEER-MakeMaker-Markdown-Pod-VERSION.tar.gz from a GitHub
release, MetaCPAN, or a CPAN mirror, replace VERSION, and verify it
with:

    gh attestation verify ASPEER-MakeMaker-Markdown-Pod-VERSION.tar.gz --repo aspeer/pm-ASPEER-MakeMaker-Markdown-Pod

A successful verification confirms that the archive checksum matches an
attestation from this repository. The workflow publishes the same
archive to GitHub Releases and CPAN. Older releases and GitHub's
automatically generated source-code archives are not covered.

SYNOPSIS

With ExtUtils::MakeMaker:

    perl -MASPEER::MakeMaker::Markdown::Pod Makefile.PL
    make doc

The markpod command is installed by Markdown::Pod::Embed:

    markpod --inplace lib/My/Module.pm
    markpod --extract-markdown lib/My/Module.pm > lib/My/Module.pm.md
    markpod --extract-pod lib/My/Module.pm

For processing without MakeMaker, use the engine directly:

    use Markdown::Pod::Embed;

    my $markpod = Markdown::Pod::Embed->new({
        dialect  => 'GitHub',
        nobackup => 1,
    });

    my $changed = $markpod->markpod_process_and_update('lib/My/Module.pm');

The MakeMaker import hook adds doc and readme targets to the generated
Makefile. It also retains the project's established MakeMaker
configuration, dependency, metadata, provenance, and install-map
behavior.

The same complete integration can be enabled optionally inside
Makefile.PL:

    use ExtUtils::MakeMaker;

    eval {
        require ASPEER::MakeMaker::Markdown::Pod;
        ASPEER::MakeMaker::Markdown::Pod->import();
        1;
    };

    WriteMakefile(
        NAME         => 'Example',
        VERSION_FROM => 'lib/Example.pm',
    );

The import must run before WriteMakefile. If the module cannot be
loaded, the silent eval leaves the ordinary MakeMaker configuration in
place.

DESCRIPTION

ASPEER::MakeMaker::Markdown::Pod lets a distribution keep documentation
in Markdown while still embedding generated POD in Perl modules and
scripts. The Markdown source can live in a sidecar file such as
lib/My/Module.pm.md, or inside a POD block marked with =begin markdown
and =end markdown.

When a file is processed, Markdown::Pod::Embed converts the Markdown to
POD and writes a merged documentation block back to the Perl file. The
merged block keeps the original Markdown and appends the generated POD,
so the Markdown remains editable while tools such as perldoc, pod2man,
ABSTRACT_FROM, and CPAN indexers can consume normal POD.

MARKDOWN SOURCE PRECEDENCE

The processor uses a simple precedence rule:

1.  A same-path sidecar file ending in .md wins.
2.  Otherwise, embedded Markdown in a POD block is used.
3.  Otherwise, existing plain POD is left unchanged.

For example, lib/My/Module.pm.md is the source for lib/My/Module.pm. For
a script, bin/tool.pl.md is the source for bin/tool.pl.

MAKE TARGETS

The MakeMaker integration is deliberately separate from Markdown
processing:

- ASPEER::MakeMaker::Markdown::Pod inherits the common lifecycle
  behavior from ASPEER::MakeMaker.
- ASPEER::MakeMaker::MM::Import installs and implements the MakeMaker
  lifecycle hooks.
- ASPEER::MakeMaker::Markdown::Pod::MM defines and runs the doc and
  readme targets.
- Markdown::Pod::Embed selects Markdown, converts it to POD, and updates
  the Perl source.