seattlerb/minitest — pull request #411 by tadman (2014-03-13 00:59:38+00:00)
Title: Use Markdown for README

I'm not the only one confused why this is an issue, the majority of the projects I've seen use Markdown. As Minitest ships with Ruby as the default testing tool it's especially important to have documentation looking its best. No doubt this is why there are dozens of requests for the presentation of the documentation to be improved.

Even the [generated documentation](http://rubydoc.info/gems/minitest/5.3.0/frames) linked to from the [gem page](http://rubygems.org/gems/minitest) suffers from all kinds of formatting problems. It's just sort of dumped in there as-is, and without formatting the code examples are really mangled, indendation collapsed. The other [official documentation](http://docs.seattlerb.org/minitest/) seems to be handled properly because RDoc understands how to deal with that format of file.

The reasons for rejection seem to be that Markdown is not supported by `hoe` and `rdoc`.

Markdown *is* supported, as `Hoe#initialize` has the following:

self.history_file ||= Dir.glob("History.{txt,md}").first
self.readme_file ||= Dir.glob("README.{txt,md}").first

The major difference between `.md` and `.rd` is the use of `#` vs. `=` to denote headers, and this is even accounted for in the `intuit_values` method:

s =~ /^[=#]/ ? s.strip.downcase.chomp(':').split.last : s.strip

I was able to use Markdown in [a forked project](https://github.com/tadman/minitest) if I did the following steps:

* Renamed `README.txt` to `README.md`
* Converted the formatting, `=` to `#`.
* Adjusted code indentation to start at four spaces instead of two.
* Updated `Manifest.txt` with `README.md`.

All of the `rake` operations seem to work, including the documentation generator, where the `index.html` looked fine. The [Yard generated documentation](http://rubydoc.info/github/tadman/minitest/master/frames) is as significantly improved, no longer mangled.

If there's anything else here that needs to be fixed, I'll do my best to fix it, yet as far as I can tell there's no obstacle to Markdown support.