How to make my Perl module's README file compatible with Github's Markdown display?

Format your README in pod, rename it README.pod and then it works both places! Example

For my purposes I actually just generate my README.pod from the main pod by doing

$ podselect lib/My/Main/Module.pm > README.pod

One caveat, named external links don't work correctly L<GitHub|http://github.com> will unfortunately point to search.cpan.org looking for a GitHub module. I have tried to inform them of this glitch but it got me nowhere. Instead you can just use plain external links (i.e. GitHub: L<http://github.com>) and they work fine.

Good news, it appears that they have fixed this since the last time I checked!

---

Just a question, what parts of the Perl toolchain expect a README file? If you mean including it in your tarball, just be sure to add the file to your MANIFEST and it should get included.

Have you heard of POD? This is the standard documentation tool in Perl. POD is a simple text documentation format that actually lives in your code. One of the commands that come with perl is perldoc. You can use it to get the information of any Perl command. Try these:

$ perldoc File::Find
$ perldoc -f split

All Perl modules in CPAN are required to incorporate POD documentation. In fact, this is how the CPAN webpages themselves are built.

So, where am I going with this and how is this going to help you?

You should include POD documentation in your Perl program. Then, you can use the pod2text command to create your README for your Perl program:

$ pod2text myperl.pl > README

That handles half of your issue.

The other half is a bit more tricky. You need to install from CPAN the Pod::Markdown on your system. Then, you can run the pod2markdown command that comes with this module to create the markdown version of your file:

$ pod2markdown myperl.pl > README.md

The results:

• Your documentation lives, as it should, in your Perl program.
• Users can use the perldoc program to print out complete documentation of your program.
• You can use the pod2text tool to create your README file.
• You can use the pod2markdown tool to create your README.md file.
• As a bonus, you can use the Pod::Usage module that comes with Perl to show the POD documentation (or bits and pieces of it) as help text that's displayed when a user runs your program with the -help parameter.

So, one place where your documentation lives, and you're using a couple of helper programs to create the files Github and whatever Perl tools you use need.

If you don't mind using Dist::Zilla you can pretty much do away with maintaining a README entirely. For example Dist::Zilla::Plugin::ReadmeFromPod can create your README file by extracting the Pod from your main module. This means never having to write a README again.

I've never tried it myself, but you could look at something like Dist::Zilla::Plugin::ReadmeMarkdownFromPod to create your README automatically in markdown.

This may not be the exact answer you're looking for, but I think using this sort of a tool can save you a lot of time as it allows you avoid repeating yourself in your documentation.