[_getify]

I wrote a six book, 1100 page series in Markdown (all on github). I write all my blog posts in Markdown.

I'm sorry but I just can't sympathize with any of the complaints leveled against Markdown. They are so minor and compared to the massive adoption of the common bits of Markdown, there's no chance I'd ever choose to write anything in any other markup than that just for those small annoyances.

I don't need custom extensibility when I can just add HTML. HTML is pretty good at markup, and it enhances the markdown in those rare occasions where what's provided seems too limited. The very last thing I'd want to do is literally write code as an extension to my markup language. The only code in my markdown is inside nice tidy code blocks for display purposes only.

I also use JSON for configuration, even though many have tried to convince the community that YAML or some other format is better. I pre-process my JSON to strip it of "non standard" comments, and I'm quite happy that I chose the by-far-defacto-standard there instead of going off the beaten path.

[sigsergv]

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.

[_getify]

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.

[falcolas]

To your second point if you use a YAML parser, you can continue to consume and emit your JSON files and get comments for free. Plus, when you get to a use case JSON doesn't support, you can continue to use the same parser for the one-off.

[_getify]

YAML claims to not be markup, but it clearly is a markup for data (significant whitespace/indentation, etc). When I want to do markup, I use Markdown.

When I want to data serialization, I use JSON. It's incredibly easy to strip comments (and whitespace, for that matter) from extended JSON before transmitting and/or parsing. I wrote `JSON.minify(..)` for that years ago, and it's literally never been a problem for me since.

[falcolas]

YAML is markup in the same way that XML and JSON are markup. All three are methods of serializing data into text documents.

It also offers several advantages over JSON, in that it can also store and sanely represent relational data, has support for comments built into all YAML parsers, and it can be used to represent data structures that don't fall into the list/hash map paradigm.

[forsaken]

Curious how you cross-referenced across the books? Did you do listings of API's?

Markdown is great for text content, not for formal documentation.

[_getify]

The books were intended as source material for publishing, so I didn't embed any crosslinks in the documents.

However, I always use markdown for all my OSS project documentation (READMEs, etc), and I do lots and lots of cross-referencing in that context. I use simple markdown links to named-section anchors.

It's a tiny bit more manual than I'd like, but it's never stopped me from doing technical documentation effectively.

[accordionclown]

markdown can indeed work "good enough" for books.

assuming you're using one of the extended flavors.

but once it comes to the repurposing of your text, switching to another flavor (for many good reasons) will cause _many_ undesirable wrinkles to appear, with a lot of them being rather difficult to find.

you might think this is a problem you'll never face. i hope, for your sake, that you are right about that.

but don't say that you weren't warned.

because the experience is unhappy, and tedious.

and not what you'd expect from a "plain-text" format.

the _idea_ for markdown (which, by the way, should be credited to ian feldman, with a follow-on by dean allen) is spot-on. but the gruber realization is short-sighted. (and, alas, stubbornly so, for absolutely no good reason.)