ASPEER-MakeMaker-Markdown-Pod

 view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN


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
MakeMaker extensions in the generated global `PERLRUN` command.

`make doc`
: Recursively converts DocBook article XML beneath `doc/` to sibling Markdown
  files, independently of `MANIFEST`. It then processes Markdown sidecars listed
  in `MANIFEST` and merges them into matching `.pm`, `.pl`, or executable targets.
  Markdown files under `t/` are ignored so test fixtures are not rewritten.

`make readme`
: Builds `README` from an existing `README.md`. When neither README file exists,
  it first creates a regular `README.md` from sidecar or embedded Markdown in
  the `VERSION_FROM` file. An existing plain `README` without `README.md` is
  left unchanged, and no file is created when `VERSION_FROM` has no Markdown.

Status output is written to STDERR. Normal output is intentionally compact:

```text
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
```

# DOGFOODING

This distribution uses its own sidecar workflow. The important modules and the
public integration classes have adjacent Markdown files:

```text
lib/ASPEER/MakeMaker/Markdown/Pod.pm.md
lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm.md
lib/ASPEER/MakeMaker/Markdown/Pod/Constant.pm.md
lib/ASPEER/MakeMaker/Markdown/Pod/MM/Constant.pm.md
README.md
```

Running `make doc` regenerates embedded POD in the modules from those files.
Running `make readme` regenerates `README`.

# DEPENDENCIES

The conversion implementation is supplied by `Markdown::Pod::Embed`. The
`ASPEER::MakeMaker::Markdown::Pod` class retains the processing methods as a compatibility
facade, while new conversion-only code can use `Markdown::Pod::Embed` directly.
The MakeMaker lifecycle and utility implementation is supplied by
`ASPEER::MakeMaker`; this distribution does not vendor copies of its
`MM::Import` or `MM::Util` modules.

README generation uses `pandoc`. If `pandoc` is not available, README generation
will fail and the README-specific test is skipped.

# AUTHOR

Andrew Speer <andrew.speer@isolutions.com.au>

# LICENSE AND COPYRIGHT

This file is part of ASPEER::MakeMaker::Markdown::Pod.

This software is copyright (c) 2026 by Andrew Speer
<andrew.speer@isolutions.com.au>.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

Full license text is available at:

<http://dev.perl.org/licenses/>



( run in 0.717 second using v1.01-cache-2.11-cpan-234fa220139 )