
ReStructuredText vs. Markdown for documentation - ingve
http://zverovich.net/2016/06/16/rst-vs-markdown.html
======
jawns
One point that's not really touched upon is the fact that it really does
matter whether the person writing the documentation is a technical writer or a
developer.

If you're a tech writer, you're probably interested in using the best tool for
the job, because writing documentation is what you do day in, day out. If
ReStructuredText is the most powerful format, then you're going to strongly
lean toward that.

If you're a developer, however, writing documentation -- while you may
recognize its necessity -- is a task that is often a slog. It's something you
do so you can get it out of the way, and you really don't want to spend very
much time thinking about the "how." You especially don't want to spend very
much time learning the intricacies of a new markup format, unless you
absolutely have to.

I say this as a developer who is also a writer. I enjoy writing, but I know
many developers don't. And if Markdown makes it easier for them to write
documentation, either because they're already familiar with it or because it's
just a simpler format, then I'm all for it, even if ReStructuredText might be
a bit powerful overall.

~~~
samastur
Also, there are a bunch of editors for writing Markdown for most platforms and
few (any?) for ReStructuredText.

~~~
kevhito
You mean like vim, emacs, nano, kate, notepad, notepad++, wordpad, or any
other plain text editor?

Really - I don't get this impulse at all. From my perspective, the entire
point of markdown (and RST I assume, though I haven't used it) is that you can
easily read and write it using any plain text editor.

If you are going to need a specialized editor to write it, you might as well
use html, docbook, docx, odt, troff, rtf, or any of the zillion other formats.

~~~
micah_chatt
Back to the main point, for non-developers all of those can be quite confusing
especially when you're used to Word/Google docs/etc. A text-only editor where
you don't get live feedback is quite an adjustment and there is a cognitive
switch to the text you're writing and imagining how that text will be
presented.

------
snide
A couple years ago I put together one of the more popular themes for Sphinx.
It's the one used by Read The Docs and you've likely seen in countless times
when searching for Python libraries.

I prefer Markdown.

It's readable and easy to start writing by non-technical folk. More than that
that, it's less flexible and isn't as likely to be destructive. At the end of
the day rST is as complicated and as flexible as something like HTML. The
biggest problem is its ability to nest markup. Markdown is pretty flat and
you're not putting lists within tables within blockquotes. As someone making a
theme, it was pretty difficult to style against the level of nesting that
people end up using rST for. This is of course me bitching about how people
write their rST, but there it is. I think rST by nature leads to inconsistent
markup.

Basically what I'm saying is. At that point, I'd rather just write HTML. rST
sits in some weird middle world where it can get very verbose, but you end up
losing all the simplicity that you wanted in the first place.

Also want to note that rST doesn't HAVE to be so complicated. Plenty of people
write clean, rST docs. However, as someone who spent a good deal of time
learning the Sphinx system and the markup quirks of rST, in general I ended up
seeing people use it in all sorts of crazy ways which then led to weird
styling errors.

When it came time to document my own projects, I just built a simple markdown
system with a tree structure and added some syntax highlighting. That's gonna
get most projects 95% of the way there. While you can do a lot more with rST
and it is really powerful, I really think it's only for those 5% of projects
or more than likely, scientific documentation that needs more context.

~~~
vitaut
I don't think there is anything in RST that encourages deep nesting level or
verbose markup, on the contrary with default roles it can be _more_ compact
than Markdown. If you look at good documentation examples, like The Python
Standard Library documentation
([https://docs.python.org/3/library/index.html](https://docs.python.org/3/library/index.html)),
nesting is very limited and the documentation source is very clean and
readable.

~~~
snide
I agree with everything you say. All I'm saying is that in practice, the rST
docs I saw, and the issues that came up around theming rST docs led me to
believe that the flexibility of rST was its biggest problem (and strength).

Markdown doesn't have that problem because you can't do much with Markdown.

~~~
gshulegaard
I think you are both right. This discussion reminds me of the classic C vs.
C++ discussion.

> [http://thread.gmane.org/gmane.comp.version-
> control.git/57643...](http://thread.gmane.org/gmane.comp.version-
> control.git/57643/focus=57918)

Ultimately, I lean towards rST since you can combat complexity with "good
practices" (as a Python guy this is akin to being _Pythonic_ ) but the
opposite is not true for less complex implementations.

But there are merits to both approaches.

------
geerlingguy
Similar previous discussion:
[https://news.ycombinator.com/item?id=11292280](https://news.ycombinator.com/item?id=11292280)

And from my comment in that thread:

After having written a fairly popular 400+ page book, and dozens of
documentation sets in Markdown (and having worked on a few in other
languages), I have to say—Markdown is _good enough_.

It will take an order-of-magnitude difference to unseat Markdown as the
'simple plain text formatting syntax' default, IMO. But use what makes you
productive and is most conducive to writing effortlessly!

~~~
sevensor
I wrote my dissertation in markdown because LaTeX added so much noise to the
text. In the end I had to go back and manually reformat chunks of it in LaTeX
(especially the floats), but it was still worth it for all the bits I never
had to write LaTeX for. In the end, it's not either-or, it's Markdown plus
conversion to something with more knobs to turn. (All thanks to Pandoc!)

~~~
aninhumer
Pandoc even lets you include LaTeX in your markdown, so you can just use it
inline for the few times you need more control, without having to faff around
editing the output.

~~~
copperx
What happens if you include LaTeX in Markdown and select a different output
format, such as docx? is it just ignored?

~~~
zzleeper
Yes. Depending on what are you including, a better alternative might be to use
Pandoc filters that change their output depending on the output format. So for
latex you might end up with fancy figures side-by-side, but for word you just
have them as figures one after an other

------
lsllc
Don't forget asciidoc; Markdown-like but much more powerful.

[http://asciidoc.org](http://asciidoc.org)

~~~
janvidar
I must add Asciidoctor. Which is mostly compatible with Asciidoc, but even
more powerful.

I have spent a lot of time trying to make Asciidoc create beautiful PDFs for
technical documentation, but Asciidoctor makes it all a lot easier to
customize its own stylesheets.

The only negative thing about it is that it is hard to install since it
typically isn't found in your distros package repo by default.

~~~
rz2k
And perhaps, just one more standard to unify all of them!

~~~
metasean
Obligatory xkcd - [https://xkcd.com/927/](https://xkcd.com/927/)

------
bediger4000
This whole argument presupposes that anyone who cares will get a choice in the
matter. We all know that most bespoke software is written for corporations.
And despite the immense drawbacks of "Word" (too many to mention, but let's
start with autocapitalization...), most bespoke software is documented in
"Word" despite "Word" not being fit for that use.

To me, this is like watching intense baseball fans argue who was better, Babe
Ruth or Joe Dimaggio - neither one of them is going to play again.

~~~
rubidium
This!

So here's a story: I work at a large engineering company building custom
automated research systems. The system engineers do the the
design/development/testing and documentation.

I have been searching for nearly 9 months for a documentation system to
replace our current documentation system (500 Word docs in an EDMS). Goal is
to increase re-usability and decrease maintenance cost by something more like
a wiki/markdown system.

The problem is, even though formatting and maintenance of Word docs is
abysmal, they make inserting images and references drop dead simple. Plus,
everyone has it installed on their machine.

All the markdown versions don't have good references or image support (plus
the best IDE is gitbooks which is... buggy). RsT is too much of a burden to
setup. These are engineers writing, not programmers.

I've looked into Confluence, Gitbooks, Dozuki, Inkling, Sphinx, ... nothing is
quite so friction-less to "just write the docs" than Word.

~~~
copperx
I agree -- I originally wanted a markup language to do away with LaTeX for
typesseting but then I realized that getting image sizing and placement right
on any markup language is even more painful than with LaTeX, so I just never
jumped ship.

I still wish I had a publishing toolchain that produced multi-format output
(HTML5, docx, ePub, Kindle, and plain text) from the same source file. It can
be done with LaTeX sources but the result is sub-optimal.

~~~
r0muald
As I wrote in another comment, this can be done quite easily with Pandoc. It
is a really powerful processing tool and with the right set of templates it
can do wonders. Have a look at Kieran Healy's work:
[https://kieranhealy.org/blog/archives/2014/01/23/plain-
text/](https://kieranhealy.org/blog/archives/2014/01/23/plain-text/)

~~~
rubidium
For some definitions of "easily". For a programmer, yes.

For an enterprise organization with a full gamut of technical ranges from
"maintain 40 github repos for fun" to "I still don't trust anything but Word,
Excel, Powerpoint and email", pandoc is not the solution (as nice a tool as it
is).

------
arjie
This is a non-issue. Here's a simple algorithm:

1\. Do you want to write something that MD is sufficient for? Write MD.

2\. Do you want to write something that you need RST for?

2a. Is your document already in RST or is there no document? Write RST.

2b. Is your document in MD? Pandoc to RST. Pretty print. Write RST.

The reason this is useful is that the 90% use-case is probably hit by MD. You
may never need RST. And you won't spend more time deciding and discussing than
actually doing because this algorithm only takes a few seconds to execute.

------
1wd
RST has some great ideas (as mentioned in the article, roles and directives
are fantastic ideas). But it also has quite a lot of unnecessary complexity
built in. It's also great that it (kind of) has a specification, not just a
bunch of hand waving. But even with the specification there seems to be no
independent re-implementation, so I wonder if the specification is really
complete. It also makes some syntax choices that just make no sense at all to
me. Making the most basic and important feature (bullet lists, titles)
annoying to use was not a smart move.

The (only) good thing about Markdown is it's (allegedly) simple. IMO it's on
the one hand not simple enough (e.g. HTML has got to go) and on the other hand
it's too simplistic.

Ideally I would like to have a tiny core specification with a clean and simple
standardized mechanism for extensions like roles and directives. With a bunch
of standardized but optional extensions. Only the most important features (90%
of usage) should get special syntax (bold, bullet lists, titles, roles,
directives). For everything else (90% of features) there should be a named
role or directive.

Trac actually uses a similar system. linkExtensionName:content,
[[extensionName(content)]] or {{{#!extensionName multiline-content }}} is all
you need to remember. Could be simplified a bit, but it's quite usable.

~~~
vitaut
I've used a lot of RST and from my experience the specification is very
accurate. If there is some inconsistency, it should probably be considered as
a bug and reported to Python docutils. What exactly is the problem with bullet
lists? AFAICS they are pretty much the same in Markdown and RST.

~~~
1wd
In RST you must have a blank line between parent bullet and child bullet. This
really discourages adding small child bullets.

In RST you must indent child bullets exactly to the indentation level where
the text starts in the parent bullet.

~~~
slgeorge
a. In RST you must have a blank line between parent bullet and child bullet. I
don't think that's correct, this works:

# Remove the spaces at the start to put in a file (HN rendering)

    
    
      * Bullet 1
          * Sub-bullet 2
      * Bullet 2
    

# Both worked fine:

    
    
      $ rst2html --verbose test.rst test.html
      $ pandoc --output test.html test.rst
    

b. In RST you must indent child bullets exactly to the indentation level where
the text starts in the parent bullet.

Also untrue as far as I can see. Vim does do automatic indents for me so they
have to be consistent AFAIK, but not to the `exact` same level as where the
text starts in the parent bullet.

~~~
1wd
a. That's not a child bullet, it's a paragraph continuation. This exactly
demonstrates the problem with RST.

Check the specification:
[http://docutils.sourceforge.net/docs/ref/rst/restructuredtex...](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-
lists) See "examples of incorrectly formatted bullet lists", or
[http://docutils.sourceforge.net/docs/dev/rst/problems.html#b...](http://docutils.sourceforge.net/docs/dev/rst/problems.html#blank-
lines-in-lists) or [http://docutils.sourceforge.net/FAQ.html#could-the-
requireme...](http://docutils.sourceforge.net/FAQ.html#could-the-requirement-
for-blank-lines-around-lists-be-relaxed) It's a well known problem.

b. Check the spec. It must be exactly aligned. If it's not exact it's not a
child list. It's just an independent list with random indentation.

See e.g. [http://stackoverflow.com/questions/5550089/how-to-create-
a-n...](http://stackoverflow.com/questions/5550089/how-to-create-a-nested-
list-in-restructuredtext)

~~~
slgeorge
oh wow, didn't know that. Arg! _all_ my personal notes have list that will
have to be re-formatted that!

------
pfultz2
First, there is commonmark that is trying to standardize markdown. There is
also recommonmark which will parse commonmark for sphinx:

[https://github.com/rtfd/recommonmark](https://github.com/rtfd/recommonmark)

However, commonmark currently lack support for tables, so I fall back on rst
for tables(actually I think the syntax for tables in rst is much better than
tables in other markdown flavors).

Also, resolving links using commonmark in sphinx is a mess, right now. I
actually extended recommonmark so sphinx will properly resolve cross
references(including reference to elements in a domain). However, I had to
update sphinx as well, which I have a PR open with no response from them,
here:

[https://github.com/sphinx-doc/sphinx/pull/2644](https://github.com/sphinx-
doc/sphinx/pull/2644)

It seems unfortunate that sphinx devs are unresponsive to contributions. The
devs for mkdocs are a lot more responsive, but seem more interested in
monetary contributions, unfortunately.

------
binarycrusader
My choice is Markdeep: [https://casual-effects.com/markdeep/](https://casual-
effects.com/markdeep/)

------
mzs
Anyone remember that Show HN which let you create diagrams from simple text
like this:

    
    
        A <----- B -----\
                        |
                        V
                        C
    

Then there was a link in the discussion to a similar tool.

~~~
mzs
Found it thanks to the two suggestions below and a search, shaky:

[https://news.ycombinator.com/item?id=10290073](https://news.ycombinator.com/item?id=10290073)

------
rcarmo
I'm still using Textile. My blog engine
([https://github.com/rcarmo/sushy](https://github.com/rcarmo/sushy)) can cope
with ReST, Markdown, Textile, raw HTML and iPython notebooks, and I still turn
to Textile for complex tables and other niceties. Out of the 7000-odd pages on
my site, most complex pieces are Textile (although most newer items are
Markdown).

I find ReST incredibly awkward to use, really, because it's anything but
intuitive - both Textile and Markdown are easier to write off the cuff.

More importantly, though, I really wish that Textile, Markdown, ReST, etc.,
were formally specified as PEG grammars or similar. There's just too much
variation, and "standards" or specs defining them tend to be written in
ambiguous English rather than something that could be formally validated and
easily ported across to new languages (rather than the spaghetti messes of
regexps that most parsers turn out to be when you look at the source).

~~~
dflock
Here you go: [http://commonmark.org/](http://commonmark.org/)

~~~
rcarmo
Actually, I was thinking of CommonMark when I wrote that. The spec is still
ambiguous, and a reference implementation is not a formal grammar...

------
makecheck
While I do like simple markup, I think that all markup languages will become a
lot better when text input hardware slightly evolves. We are so close to
having this.

We have Unicode but most of its symbols are a pain to generate on conventional
keyboards.

We have touch-screens but desktop computer keyboards don’t offer them and
software on phones/pads still tries a bit too hard to emulate a conventional
keyboard layout.

Imagine if all _standard_ keyboards had touch displays on the side to quickly
flip between tables of related symbols, optionally with some context-sensitive
mode? Then, instead of having to use creative ASCII tricks to make it “simple”
to describe what you want, you just _do it_ through your input device.

Ultimately I think markup languages will have to distill their features down
to a few structural elements, and rely on Unicode (and easier Unicode input
methods) to handle what is currently being done with ASCII hacks.

~~~
jessriedel
Would the Optimus Maximus keyboard work?

[https://www.google.com/search?q=Optimus+Maximus+keyboard&tbm...](https://www.google.com/search?q=Optimus+Maximus+keyboard&tbm=isch)

[https://en.wikipedia.org/wiki/Optimus_Maximus_keyboard](https://en.wikipedia.org/wiki/Optimus_Maximus_keyboard)

It exists but hasn't taken over the world.

Apparently Apple's working an OLED display above their keyboard.

[http://9to5mac.com/2016/05/23/apple-prepping-thinner-
macbook...](http://9to5mac.com/2016/05/23/apple-prepping-thinner-macbook-pros-
with-oled-screen-above-keyboard-touch-id-for-q4/)

~~~
copperx
A keyboard with OLED keycaps that change depending on the context would be
reason enough to get a new laptop altogether, even though I have a brand new
one.

As someone who context-switches from XCode to IntelliJ to Photoshop to Emacs,
sometimes I confuse the shortcuts, and I don't learn more shortcuts because
I'm afraid they will not carry over to other programs. Having discoverable
shortcuts would be amazing.

~~~
jessriedel
Yea, it always surprised me that Apple hadn't fully copied this idea for Mac
books. Maybe it needed to wait for OLEDs?

------
carlob
Re: 30 flavors of Markdown: did you guys know that Atlassian uses two
different flavors of MD for jira and bitbucket?

~~~
dv_dt
Since Atlassian acquired bitbucket, the products have two separate development
histories, so I'm not too surprised.

~~~
carlob
But if one of your main selling points is integration, you'd better
standardize to one, especially if (as an other commenter pointed out) the one
in bitbucket is subpar.

~~~
dv_dt
No argument there - but no surprise either that upgrading bitbucket's markup
might be something lower down on the priority list for the Atlassian
engineering team either. :)

------
dredmorbius
Having authored texts in nroff, groff, HTML, DocBook, Markdown, ASCIIDoc, and
LaTeX, as well as numerous proprietary formats and word processors, my
considered view is this:

Let authors use the fucking tools they know and prefer.

Organise common text through translation tools. Pandoc is fucking amazing.

Formatting for final production is a separate task.

(Not without some irony, I'm reviewing a set of guides and commentaries on
productivity and creativity in a few other tabs....).

 _When you are writing_ your most important task is to capture the gist of
what's in your head onto a tangible medium. If that means fucking Messinian
marble and diamond chisels, so be it.

The marginal productivity gains _for someone already proficient in a tool_ are
low in switching to something else, _relative to domain knowledge_.

The challenge is that you're then stuck with high-level, vs. low-level
definitions and tools. Which is where the whole "what do I use for creating my
documents" question ends up at.

Systems such as HTML5 (the semantic elements, not all the canvas and DRM
crap), or LaTeX, or DocBook, are hugely useful here _because their definitions
are largely semantic_. You _write the structure, not the style_.

After that, so long as a tool or language can produce ingestible input given
an author's output, that's fine.

And, frankly, by the time you're worried about specific low-level structure,
use a dedicated tool which provides that. My experience with LaTeX was that it
was actually _amazingly_ simple to use for basic creation -- it gets out of
the way. Paragraphs as linefeeds, rather than HTML's incessent <p> </p> pairs,
helps immensely. For more complex structures, you can go back and add what's
needed later.

Markdown offers a wide set of capabilities with the option of fallback to
HTML, which again is powerful and a good option for composing.

And there's value in simplicity.

------
abathur
I'm in the middle of converting a project's legacy plaintext documentation
(emulating man page format) into RST/Sphinx. The support for semantic markup
with roles and directives was attractive for my goals (without falling down
the rabbit hole, being able to: 1. translate from one source to formats
compatible with both presentation-markup and semantic-markup, and 2. lint the
docs).

I've come to rue this decision in some ways. I like what I've been able to
accomplish, but I've found most customization of default Sphinx and docutils
behavior to be torture. I don't mean to drag contributors to those projects
through the mud--they work well if you can just write documentation without
fiddling much.

------
zzleeper
(Shameless plug) If you want to extend markdown, consider this:
[http://scorreia.com/software/panflute/](http://scorreia.com/software/panflute/)

It's a Python package that allows you to extend markdown through pandoc
filters. It allows you to easily manipulate the AST created by Pandoc to add
any number of features.

For instance, I wrote my dissertation in Markdown , and used this to include
algorithms, CSV tables, include directives, etc.

------
MrBingley
Another interesting publishing system is Pollen [http://docs.racket-
lang.org/pollen/](http://docs.racket-lang.org/pollen/). It integrates with
Racket to give you the full power of a programming language while writing
markup. The guy behind it, Matthew Butterick, is a typographer and has put a
lot of work into it.

------
imron
When I started writing the documentation for a software product I make I went
with Markdown. It was what I knew and I thought it was great.

As I started writing the documentation though, Markdown's drawbacks became
more apparent. Especially as the software I'm making is multi-platform and
there are features that exist in one platform and not the other and I'd like
to include/exclude documentation of those features based on platform, and the
fact that I'd like the documentation for each platform to contain images from
the program running on that platform, and so on, and this is not something
that Markdown handles well.

And so I switched to ReStructuredText. RST is not as clean or as simple to
write compared to Markdown, however if you are producing documentation then it
is much more flexible. I can live with less clean syntax in order to get the
flexibility to do what I need to do.

------
bpchaps
What blows my mind is that every time I need to write anything in markdown
(once a month or so), I can never _ever_ figure out how to use it without
doing tons of googling. Why can't sites add some easily accessible
documentation?

Hacker news, tumblr, reddit, github all do it. Honestly, if it didn't look
fine in the editor and then throw an apeshit fit when posted, it wouldn't be
that frustrating. But I'm so damn tired of hitting "preview" or editing my
posts after posting because of misleading previews and text boxes.

------
jdeisenberg
Tables in RST are far more difficult than in Markdown; you have to essentially
draw the table you want.

In both, it is difficult to have a block of code with one line in bold, or
italicized for emphasis. (The same seems to hold for asciidoc.)

Which is why I eventually gravitate back to HTML. (See
[https://github.com/oreillymedia/HTMLBook](https://github.com/oreillymedia/HTMLBook)
as well - full disclosure: I have done writing for O'Reilly.)

~~~
slgeorge
For standard RST tables I use vim-table-mode
([https://github.com/dhruvasagar/vim-table-
mode](https://github.com/dhruvasagar/vim-table-mode)) which is fantastic as it
automates RST or markdown tables.

There are some other RST table types:

a. List table: Pretty simple to use
([http://docutils.sourceforge.net/docs/ref/rst/directives.html...](http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-
table))

b. CSV table Supposed to be used for CSV imports I guess but I've never used
it
([http://docutils.sourceforge.net/docs/ref/rst/directives.html...](http://docutils.sourceforge.net/docs/ref/rst/directives.html#id4))

------
curiousdude99
org-mode + pandoc let you convert org files to anything

------
itazula
Leanpub promotes a superset of Markdown called Markua. It is claimed that
Markua is more suited to the writing of books and documentation. See
[http://markua.com/](http://markua.com/) Personally, for my projects, I use
rST, but that is only because the wind happened to be blowing that way the day
I made my choice.

------
tjl
I really wish Adobe didn't screwup FrameMaker. It was on all the major
platforms and did its job. Then, they went and dropped it from everything
except Windows and it's basically languishing ever since.

I wrote a number of documents in FrameMaker back in the 90s and I loved it. I
really wish I had something like it now.

------
flarg
I've always preferred RST just because there is a wonderful PDF renderer
called rst2pdf [0]

[0]
[http://rst2pdf.ralsina.me/stories/index.html](http://rst2pdf.ralsina.me/stories/index.html)

------
Animats
In the real world, people use Microsoft Word, or even LibreOffice Write. Yet
another flavor of Markdown is not helping.

~~~
hobarrera
> In the real world, people use Microsoft Word, or even LibreOffice Write.

Please point to towards an API or library documentation written in the native
format of either of those. In 10 years as a developer, I've never come across
such a thing.

> Yet another flavor of Markdown is not helping.

Agreed. That's pretty much what the article states, and RST, luckily, is not
that.

~~~
ygra
The C# and PowerShell specifications are written in Word ;)

In any case, there's a lot of things people use in-house and never bother to
tell the outside world about, and you'd be surprised how far that is from what
people on HN or Github habitually use.

------
peatfreak
Why is the choice between these two? Both are very limited in what they can do
for documentation of any complexity.

