Don’t Use Markdown for Documentation

Re:Don’t Use Markdown for Documentation by sigsergv on Tuesday March 15, 2016 @11:59PM (#11294909)

Markdown is fine for books, but not for technical docs.

Techdocs have lots of cross references and other similar elements, their implementation in all markdown “standards” is really bad.

ReStructured text is much, much better.

[ Parent | on HN ]

Re:Don’t Use Markdown for Documentation by _getify on Wednesday March 16, 2016 @12:45PM (#11298689)

I didn't mention in my comment, but I also use Markdown for all my technical documentation (READMEs) on my dozens of github OSS projects. I have lots of cross-references and I use normal links to named section anchors (sometimes that I insert manually via HTML).

It's not perfect or even ideal, by any means, but the other benefits of Markdown are more than enough to make up for the slight annoyances here.

I don't know about ReStructured text, but I can say that none of the examples in the OP swayed me that I'm missing anything of any import.

[ Parent | on HN ]