Today I learned

Use Markdown for documentation

The most universal documentation "format" is a bunch of Markdown files inside a project's doc/ directory. Here are some projects that follow that convention:

In my opinion, "a bunch of Markdown files" is good because:

  • It's easily viewable in GitHub
  • It can be made into a Jekyll (GitHub pages) site easily
  • It can be made into a Sphinx site easily
  • It's a common documentation format that you can get some tools to generate to

You have just read Use Markdown for documentation, written on February 19, 2015. This is Today I Learned, a collection of random tidbits I've learned through my day-to-day web development work. I'm Rico Sta. Cruz, @rstacruz on GitHub (and Twitter!).

← More articles