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.

• --footer footer-string, --footer-file file

  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.