The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

pod2github - Make pretty GitHub readmes from your POD

SYNOPSIS

 $ pod2github lib/Foo/Bar.pm > README.md

DESCRIPTION

This program converts your POD into Markdown, with GitHub-specific formatting of source code. Because your project's README.md probably diverges from your POD, pod2github offers various other functions:

  • Improve formatting: syntax-highlight Perl sections, and render command-line options, methods and functions as code. Title-case allcaps headers.

  • Hide or inline arbitrary sections

  • Optionally add a header or footer

OPTIONS

--exclude HEADER,HEADER...

Exclude one or more sections from the output. For this and below sections, header matching is case-sensitive and matches headers at any level.

--include HEADER,HEADER...

Include only the listed sections in the output.

--inline HEADER,HEADER...

When these sections are encountered, remove the header but keep the section body. Useful to remove the 'Name' header from the top of your readme.

--header header-string, --header-file file

Output the specified header text or the contents of the specified file before outputting the converted input.

Output the specified footer text or the contents of the specified file after outputting the converted input.

--title-case, --no-title-case (default: on)

Convert section headings to title case.

--syntax-highlight, --no-syntax-highlight (default: on)

Convert verbatim code blocks to Github Flavored Markdown blocks, with Perl syntax highlighting.

--shift-headings OFFSET (default: 1)

Shift POD headings by offset to yield a smaller Markdown heading. The default of 1 maps =head1 to a level-2 heading (i.e. ##) which is nicer than the overly large level-1 headings. Set to 0 to disable.

--input FILENAME

Set input filename, instead of STDIN/command line argument.

--output FILENAME

Set output filename, instead of STDOUT.

--config-file FILENAME

Load configuration from FILENAME (see below)

--help

Show this POD and exit.

--man, --perldoc

Show this POD in your man pager, and exit.

--version

Output version and exit.

--usage

Output the synopsis section only and exit.

YAML CONFIGURATION

Instead of passing command line arguments, configuration can be loaded from a file named pod2gitub.yaml (or .yml; optionally preceded with a single dot). Or from any other file via the --config-file option.

The YAML document should contain a top-level dictionary mapping keys to values. Keys may use either underscores or dashes. For binary options, use a value of 0/1.

An example configuration:

 input: lib/Pod/Github.pm
 output: README.md
 inline: NAME

AUTHOR

Richard Harris <richardharris@gmail.com>

However the hard work is done by Pod::Markdown by Randy Stauner.

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 Richard Harris.

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