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

Question

I've authored the README file in my Perl module in Markdown. Github treats this README file as plain text. I tried renaming the file to "README.md"—which looks great on Github, but is invisible to Perl tools that look for a file named "README."

Is there any way I can have both a README file, and have my Markdown formatting be interpreted correctly by Github?

The only option I could come up with was to have both a README and a README.md, but I'd prefer not to have to manually keep the two files in sync.

Thanks for your help.

Answer 1

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.