/ 
Pod-Github-0.04
River stage zero No dependents
/ pod2github

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.

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