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

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.

Answers


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.


Another solution if you really want to distribute your module with a Markdown README, that doesn't involve Pod is to :

  • rename your README file to README.md
  • update the previous change in the MANIFEST file

I think it can be an interesting solution because more people know Markdown syntax than Pod one. As the aim of the README file is to be read by anyone, Markdown should be considered.


I was just looking for a solution for this problem and decided to use Dist::Zilla::Plugin::ReadmeAnyFromPod as it understands =attr and =method tags from Pod::Weaver.


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.

Then automatically keep them in sync?


Need Your Help

Is it safe to rename argc and argv in main function?

c++ c main

A lot of programs use standard names for a number of arguments and arrays of strings. The prototype of main function looks like: int main(int argc, char *argv[]);. But would I break something if I ...

Best Way to Invoke Any Cross-Threaded Code?

c# .net invoke

I know that this question has been asked before, but I'm looking for a way to: