ReStructuredText vs. Markdown for technical documentation | Hacker News Reader

ReStructuredText vs. Markdown for technical documentation

eli.thegreenplace.net

64 pointsnikbackm24 comments

A big difference between ReST and Markdown is that it's very easy to accidentally write ReST that is either invalid or doesn't mean what you think it means. The Julia manual used to be written in ReST and even people (or maybe especially people) who were pretty deep down the ReST features rabbithole, regularly committed ReST that was just wrong – quotes where code was intended; incorrect hyperlinks (why is the hyperlink format in ReST so damned complicated and non-uniform – it's basically impossible to remember); bullets or lists that aren't actually bullets or lists. This is possible in Markdown, but it's much harder: by design, things almost always mean what they look like they mean. That's a huge benefit. The Julia docs are now in Markdown and accidentally broken markup is hardly ever a problem anymore.

This. Markdown is good for non-technical people who struggle with a real markup language, but reStructuredText is so fiddly that I can't figure out who's better off using it over DocBook, or HTML, or LaTeX, or even nroff.

  This is `a footnote`_? Seriously?
  .. _a footnote: http://example.com/

I agree that ReST is needlessly complicated. But Markdown isn't really that much better. Maybe it's because I'm more used to Wikipedia-style link syntax. As for bullets: Since some Markdown implementations annoyingly insist on four spaces, while others work fine without that, I'd say it's about even.

But these are all minor annoying details of either. The win of ReST is standardized extensions for anything. The win of Markdown is there's half an implementation running anywhere.

Related: my immediate thought was that this totally ignores basic aesthetics and readability. This is partly a matter of taste, but to say that the only virtue of Markdown is popularity ignores why Markdown became so popular, when ReST, Textile, and others were varyingly widespread in all of Markdown's current niches before Markdown existed. Markdown was designed above all to be pleasant to write and read in the common case of relatively simple structure and markup, and it mostly succeeds. This is a huge advantage in practice.

And yet markdown has no standard way to add captions to images. The internal docutils DOM is almost trivially mappable to a large subset of Docbook which can be done with rst2xml and some XSLT. Markdown is basically designed to map into older versions of HTML and has no hope of ever having such semantic expressiveness due to its fractured ecosystem.

Neither is any good for technical docs, Asciidoc/Asciidoctor is by far the best. You get automatic numbering, conditional includes i.e you can pull in specific pieces of code into your docs when you tag them. Look it up, it's extremely powerful and as easy to write as reST if not easier because it's more consistent.

I just read some articles on why Linux went from asciidoc to RST. Interesting read.

Links?

I guess you meant this - https://lwn.net/Articles/692704/

"When comparing the markup formats for the purposes of kernel documentation, only the table support, which is much needed for the media subsystem documentation in particular, was clearly identified as being superior in AsciiDoc. Otherwise, the markup comparison was rather dispassionate; it really boiled down to the tools themselves...

... In the kernel tree, there are no tools written in Ruby, but there are plenty of tools written in Python. It was fairly easy to lean towards Sphinx in this regard."

As I read it, Asciidoctor is still superior, but their decision was to go with something written in Python that they could adapt for these specific needs.

I really want to love ReST. Part of that is that I like writing in text but having it look good. Part of it is non-technical; I've known the ReST developer forever. And if you need to do something complex, ReST is definitely the way to go.

If I was writing a technical book, I'd probably use ReST.

But, 99.9% of the time, my needs are much more mundane and fit well within the limitations of Markdown. Usually I can just sit down and write Markdown, sometimes I need to bring up a cheatsheet. When I just need to add some documentation related to my work, Markdown is perfect.

What I'd really like is something where I can write Markdown, but if I run into needing something it can't do then switch over to ReST. Because of the overlap, that seems like it should be doable. I was looking at some static site generators that might do that, but I had limited time to evaluate them and couldn't get my existing ReST documents directly to render there so I had to get back to work.

If anyone has had any success with that, I'd love to hear about it.

Oh, that and a way to see the results without having to render and load the results (which currently involves mercurial, fabric, sphinx, and a browser for me). I don't need WYSIWIG, but a quick render would be nice.

If you're writing a book, I would strongly recommend Asciidoc syntax and the Asciidoctor toolchain.

Thanks, I'll take a look, even though I have no plans of a book. :-)

I use reST daily agree that reST itself a bit too complicated; it would be much better to have a conceptually simpler syntax, closer to that of Markdown. Also, some of their syntax choices look too artificial for a plain text format.

Yet for me reST is a clear winner, because it's extensible; it's relatively easy to a) write your own directives, substitution directives, and text roles and b) hook into the parser. For example, in my workflow I only use their parser with a few of my own extensions and only to get the parsed text as XML; once I got this, I continue with XSLT to transform it into what I need. (I use Python and lxml with my own extensions to XSLT as well, so I can, for example, manipulate files and update a whole directory tree right from XSLT.)

I think most of these tools would benefit if their parser was a separate component that could save the resulting tree into XML. (It would be ideal to have a configurable parser where you can tinker with the grammar.)

Good article, but I couldn't help stumbling over the thumbnail history of markup languages in the introduction -- in particular the assertion that Markdown, "in 2004 ... really pushed the concept over the brink of ubiquitousness". I would say that the concept of markup languages truly became ubiquitous in the 1990s, with the extremely widespread popularity of a markup language that the author didn't even mention -- the Hypertext Markup Language.

That history was supposed to cover lightweight markup languages like MD. Otherwise of course the history goes way back :)

I took a shot at using Markdown for a docutils/Sphinx "competitor" just to see if it could be done. My solution for extensions that don't require parser modifications was just to use custom HTML tags. Existing parsers know how to deal with those!

As soon as I finished it, I quickly realized that lobbying for its adoption and supporting it would be painful, but you might find it interesting.

http://steveasleep.com/computerwords

While it's technically correct that Markdown has a mishmash of implementations (and technically correct is the best kind of correct, after all), it's worth pointing out that MultiMarkdown has both a well-defined feature set that includes things like tables, footnotes, and citations, a standard way to express metadata, and has a reference implementation in C.

http://fletcherpenney.net/multimarkdown/

And, you might say, "But I've never heard of MultiMarkdown," but the reality is that if you've used Markdown for creating, well, tables, footnotes or citations, or used a YAML metadata block for a Jekyll blog, or any number of things that weren't in the original Markdown spec but that people in practice do all the time, then you've used something that was either influenced by MultiMarkdown or something that MultiMarkdown adapted.

And that last point is larger than MultiMarkdown, specifically. I'd argue that Markdown as commonly implemented and used can do an awful lot of things that are necessary for technical documentation work. This isn't to say that ReST or AsciiDoc aren't more powerful, but in practice, there's very little I've had to write that can't be written in (Multi)Markdown.

Interesting article, i had the same thoughts on MD vs RST when building commenting on RhodeCode. That's why it supports both, and i find it the most flexible solution

If by technical documentation you mean a readme page, or a few internal pages, then either are fine, as are AsciiDoc, org, etc. There's no huge advantage or disadvantage to any of them; use the one that is easiest for you to write in without having to look up cheatsheets.

A lightweight markup language is designed to for the user to quickly write something, and most of them have been designed with the goal of having programmers document their work without having to learn a complicated tool. If you need to write extensions for a lightweight markup language, you're using it wrong.

For anything more than that, I'd use something designed for technical documentation (DITA and DocBook come to mind).

Lightweight markup languages seem easy, and, in the beginning they are, but over time, as revisions pile up and more people work on it and you find you have more requirements than you thought you had, they become a huge hassle. You spend more time fiddling than writing. There's a reason professional writers tend to use richer tools - they make their jobs easier and they make the result better.

I find that markdown is good for 'simple' human readable things, but that parsers can often fall on their faces.

A particular issue I have with markdown is the bold/italic issue. However this is probably indicative of a broader issue. Markdown either does not have, or does not commonly make users aware of, an escape character which will always invoke a control-word boundary and which will never be rendered in the final text.

I've also often had different websites variations on features fail when they are nested (sometimes at all).

Latex...(drops the mike)

imho latex is too complex, it's hard to sell on this when introducing it to organization.

You're not gonna show me the syntax? Or how easy it is to extend?

¯\_(ツ)_/¯

This is not a Markdown or reStructuredText tutorial, it's a comparison on some higher-level technical grounds. It's pretty easy to find syntax examples for both Markdown and reStructuredText, and very simple googling will lead to docutils documentation on extending reST.

Reply on news.ycombinator.com