pod2github - Make pretty GitHub readmes from your POD
$ pod2github lib/Foo/Bar.pm > README.md
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:
pod2github
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
--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
Convert section headings to title case.
--syntax-highlight
--no-syntax-highlight
Convert verbatim code blocks to Github Flavored Markdown blocks, with Perl syntax highlighting.
--shift-headings OFFSET
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.
=head1
##
--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)
FILENAME
--help
Show this POD and exit.
--man
--perldoc
Show this POD in your man pager, and exit.
man
--version
Output version and exit.
--usage
Output the synopsis section only and exit.
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.
pod2gitub.yaml
--config-file
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
Richard Harris <richardharris@gmail.com>
However the hard work is done by Pod::Markdown by Randy Stauner.
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.
To install Pod::Github, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Github
CPAN shell
perl -MCPAN -e shell install Pod::Github
For more information on module installation, please visit the detailed CPAN module installation guide.