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',
    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.

The integration is loaded automatically when `ASPEER::MakeMaker::Markdown::Pod` is
imported by `Makefile.PL`. It preserves local library paths and the active