view release on metacpan or  search on metacpan

README.md  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](https://docs.github.com/en/actions/concepts/security/artifact-attestations)
for distribution archives. Install the [GitHub CLI](https://cli.github.com/)
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:

```sh
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`:

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

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

```bash
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:

```perl
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`:

```perl
use ExtUtils::MakeMaker;

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

WriteMakefile(
    NAME         => 'Example',