To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?"
Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant.
Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax.
I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
I thought Markdown was clearly very silly back when it started gaining traction amongst developer types. There were already so many other better options--even at the time--for plaintext-to-formatted document markup languages.) But still, developers were designing whole apps (CMSes, productivity apps, document management, etc) and plugins around Markdown, sometimes as businesses.
But then I realized, after using it in some apps, that wasn't really what Markdown was about. Markdown is about a bare-minimum amount of styling that is just as readable and at home in plaintext as formatted in HTML. The amount of formatting it supports is small _on purpose_, so that it fits in your brain and doesn't require a toolbar to use. It is _meant_ for things like comment fields, chat programs, commit messages, and so on. Maybe even blog articles. But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.
These days, I write Markdown even in place where it will never be rendered into HTML. Because it's quite readable as-is. (And I wish HN supported it.)
Markdown is like a virus of an idea:
1. Apparently simple enough to implement to get the basics right (not that I could do it)
2. But there is plenty of room for accidental edge cases in the implementation
3. Many then implement it with or without edge cases
4. But it’s not enough because a lot of the people who use it are programmers so they naturally want to extend it to do just a little more
5. Now the standardization effort (Commonmark) has to take all of those edge cases into account plus have to figure out how to deal with extensions (especially for popular ones)
6. Then you get a heroically (in terms of effort and grit) wordy standard
All for the initial idea which is so simple that it seems redundant: look as good plain as rendered. (Then what’s the point of rendering it, and in turn what’s the point of a formal syntax instead of the (still existing) ad hoc email and whatnot conventions?)
Right now it’s fantastic for chat applications (here you definitely want rendering and not the visible markup). It’s been pretty good for things like forum comments as well. With the exception of block quotes which are a pain to fiddle with (the only prefix syntax if you don’t include the indentation-for-code since that is de facto optional now that so many applications support code fences… all because that’s how email does it).
Slack is the absolute worst at it; I am unable to at all figure out what its "parser" (which feels like cobbled together regexes … but even then … not?) is doing.
is sometimes a link. But sometimes not! Sometimes Slack mutates your message, and then renders the mutated version — and this is visible if you subsequently edit your message, as what is now there != what you type. When it works it is nice, but when Slack decides it doesn't like that message, in particular, it can just be a pain to get it to do what you've typed.Worse to me is that Slack considers "we mutated the input you typed, and then proceeded to misrender it" as "Won't Fix/Working As Intended". (I reported it a while ago, that was the resolution.)
Google Chat is also somewhat terrible at it.
Want to italicize some text? Easy right, just do it like *this*.. nope that will bake it BOLD, gotta write it like _this_ for italics.
https://support.google.com/chat/answer/7649118
The only thing I like is that you can colorize text, but there's no syntax for it, you gotta highlight it then choose a color in the formatting toolbar.
It's annoying to no end when you memorized the syntax and Google decides to not even follow it.
I think one of Markdown's biggest mistake was making `*` and `_` interchangeable. It should have been `*bold*` and `_italics_` from the beginning.
I agree with you on that.
What about * for bold, / for italic and _ for underline?
Way back in the day when I was on IRC, I usually read them as,
… which would have made sense, if you stop to think about the characters. (But of course humans are wibbly-wobbly in what they'll choose, so context is context.) Alas, bold is now different in everything, it seems, and I can never remember which is which, aside from Discord which gives visual feedback.Slack is pretty bad yeah. It might work great if you write a whole message perfectly without typos. Then immediately when you have to go back and edit things like code snippets it gets confused: often you get raw backticks in the rendered message since it’s so confused.
And for technical stuff I very often have to edit my message.
And yes: don’t even get me started on having to think about whether I can write a link or whatever in MD or if I have to use the bells and whistles buttons in Slack.
Considering that Slack is used by both technical and non-technical users they should, well, really have a way to toggle between rendering the text immediately while typing and having it in the raw form while typing. Because editing it raw would be much less confusing for me.
This is actually an option in the settings (on desktop, at least).
Aw that’s embarrassing. Thanks.
fwiw, I find it's easiest to copy a url to my clipboard, go back to slack, type the words, then select them, and then hit ctrl-v, which doesn't get rid of the text but instead makes it a link with the selected text as the link text and the pasted text as the url.
To be fair, John Gruber offered up a completely deficient “standard” and a buggy as hell Perl parser implementation. Yet still wears “I created markdown” as a feather in his cap, strongly insists to this day that it was a good idea, and says “the canonical markdown docs are on my blog! Nothing else is markdown!” Things like CommonMark were absolutely integral to Markdown’s current success. It was way more about fixing John’s mistakes than adding more functionality.
But nobody (relatively speaking) uses CommonMark, and everyone uses Markdown
They're not separate things, but a more consistent implementation of the original idea. GitHub, GitLab, Reddit, Stack Exchange... they're all adhering to CommonMark specification, not the original Markdown specification.
It's intended to look as good as possible in both mediums. It is not possible for the raw text to look as good as the rendered text and still be easily writeable, because the raw text cannot generate visual hierarchy using font size and weight.
I suspect you know this, but when you say readable raw text seems like a redundant idea, I'm not sure what point you're trying to make.
I was referring to the sentiment that “MD looks so good that I might never even render it”.
Markdown is the Unix of rich text formats.
The hours I spent chasing down the edge cases with inline html! There’s some real nuance to the spec there.
You need inline html fairly often for anything non-trivial, and some of the rules certainly aren’t intuitive or easy to remember.
That said, like JSON, it won by being both simple to grok and good enough for most use cases.
I arrived at a similar conclusion, just from the other direction: It is really hard to get people to document. It is even harder to get those people to care a little bit about formatting.
Markdown is... limited, I acknowledge. But with a very small amount of learning, markdown is as fluent and simple to write as normal text. In fact, 90% of what I wrote before I knew markdown was valid and decently formatted markdown already.
If you asked people who don't document to document in rST or tex... then you'd have no documentation at all. Because that suddenly adds a lot of effort on top of what you want to write down.
Now for some customer-facing whitepapers and documentation, we do use rST. But there you have people who are tasked with paying some effort to create some decently looking docs. Not trying to coax developers into writing down some of their state of mind while doing stuff.
Although, I have to say, it is a sad state of afairs, if rST is already too difficult for a person with the job role "programmer" to use. If this is already the threshold, which would stop them from writing documentation, then I have my doubts about the quality of documentation, that they will write in Markdown.
Small barriers matter. Anything that kicks you out of the flow makes a huge difference. And rST is confusing enough often enough to kick you out of the flow.
Agreed. Mandate function docstrings? You'll get "Function FlargleBlab blabs the flargle" docstrings. Just useless.
Yes!
Markdown is great because it is a way to write and store documentation in plaintext, in a way non-documentarians can follow.
And it's been making a ton of headway even outside that context -- I've seen occasional formatting goofs in online newspaper articles that indicated they were authoring their content in Markdown. (Which makes sense! News rarely requires complex formatting.)
Yes, though I would expect most news-folks to use some form of WYSIWYG for writing?
Ironically, that was my argument for getting rid of Confluence. Confluence should be the low barrier to entry solution, but its buggy, clunky GUI ends up actively punishing anyone who dares try to update docs. So a repo full of markdown files with a self-merge pipeline ends up being lower-resistance.
I wonder if Spotify was right on the money with their Techdocs approach. It's all just Markdown files being rendered in another format, and the edit button is just sends you to a github or equivalent editing page. People want the idea of a platform... but do they need one?
Well, you could get similar results by just spinning up a copy of the Wikipedia software. Their formatting language even looks enough like markdown in practice (despite appearing earlier).
I guess that depends. If you're making a print manual, yeah probably not. IME markdown gets painful as soon as you start doing a bunch of tables.
Most enterprise web applications would probably be completely fine with just markdown-based docs.
I think a good example is all of the wonderful documentation that's been created with mdBook.
Heck, the Rust book was written with it, and they also made a print edition, so maybe markdown is enough even for that.
https://github.com/rust-lang/mdBook
Carol put in a tremendous amount of work to build tooling to go between Markdown and Docx. The publishers used the docx versions for print.
That doesn’t mean that I think Markdown is inadequate or the wrong decision, but it’s not just a “write in Markdown and you’re good” sort of situation.
Ah, good to know! Is that tooling public anywhere, or was it pretty tailor-made just for the Rust book?
Both public and tailor-made: https://github.com/rust-lang/book/tree/main/tools
Awesome! You and Carol rock!
Thanks! She gets 100% of the credit in this case though :)
I can find here the process of converting docx to md, but not the reverse. I see the material is checked into the repo in both formats. Does that mean the docx's are your master, and you generate the markdown from it for diffing and building HTML?
I'm investigating how to switch an organisation away from a docx-only mess of a documentation system, and it looks like you might have found a process that'd work for us, and let people keep using docx if they have to.
I wonder what all those binary blobs do to the git repo though.
Thanks for any info!
You'd have to ask Carol, with the way we split the work, she handled all of this.
From my perspective, the markdown was the master copy.
Sorry I can't be of more help!
The link below (https://github.com/rust-lang/book/tree/main/tools) could imply the book was written as Word .docx with named styles, which enabled transformation into markdown for the mdBook?
My gripe is that it really isn't. Because markdown inevitable includes images or something and the instant it does it doesn't hold up to it's killer feature. Now you can't read it properly, so now you have to find a generated version, or hunt down the images manually, or generate the output yourself.
Alternatively, the document is so trivial that even markdown formatting is too much (just distracts) and doesn't add anything of value.
It isn't that bad, it just never seems to make any sense for files. It does make sense for web forms though but that's only because you never read the markdown, you just write it and the output is generated on the fly.
When you use one of the extensions, like Hugo's figure, which has alt-text support you're about as close to that goal as possible. An image can't be stored in human readable plain text.
The alternative is WYSIWYG formats that aren't plain text.
Doesn't matter how close to the goal you get if it is on the outside...
I'm gonna be annoyed if I clone your repo, open the readme.md and now have to figure out how to read it.
Plain text is awesome, for plain text. If it isn't plain text might as well use a pdf.
There's no reason for this to be all or nothing. This seems perfectly readable to me:
Even if you've never seen markdown before, it's pretty obvious.How often do you refer to the logo? Try something like this:
You know what it is, but you have no idea what it looks like. Maybe it is a garbage picture that doesn't really add anything. Or maybe the picture is a necessity to understand the architecture of the system. Someone put the time and effort to create that picture, you'd imagine for a reason. Maybe worth having a look?Maybe, just maybe, looking at that image is a good idea to do before reading 20 pages of documentation? Probably a good idea to look at even if you only intended to glance at the documentation for 20s.
Because that's what markdown mostly is in my experience, documentation. And the images, if they exist, often are a very important part of that.
Now some images are garbage, but you don't know because the alt-text will not be "Superfluous image that doesn't add to the understanding". Maybe it depends on the reader, is the reader fluent in design patterns (and crucially, is the project following the design pattern as is or have they made their custom modifications to it?).
But in reality it will likely be a flowchart. Kind if an important piece that really help when reading the text. Or maybe just an image of a header and all the field sizes. Can you do it without it? Sure. But remember that not all documentation is perfect, it might not have had someone pouring his/her heart in it. It might have been rushed. So as often is the case you actually do need both the image and the text, not just to help understanding (which alone really is reason to make sure you look at both) - but because you need both to get all the information.
I sigh when I see a .md. Especially in documentation, because in reality that probably means that I have to either get the dependencies and look up the build process to build it myself. Or I have to go to the official project web page and browse the documentation there.
If it is a .txt or .pdf I know what I'm in for, and I know I have the tools needed to view it.
You're still using all or nothing thinking. If I wanted to see the diagram then I'd open `system-hierarchy.png` by navigating to that file and clicking on it. Besides, you rarely need to build a markdown file yourself; open it on Git[Hub|Lab] or open the project's web docs. You could prefer a .txt, but that can't display images at all.
I'm having a bit of trouble understanding the problem here as well, and kinda hope people expand on it, because insight might think of what to do better.
I edit a number of wikis. This leads to an inevitable amount of instances of having images floating aside the the text. Sometimes there's some peculiar stuff done with tables. But we never actually intermix the text content in a completely unreadable way, at least outside of templates and modules, which are NOT text content meant to be read in the first place and are NOT markdown either.
Every section of text only has text content, and the only alterations to the text come as syntax that strictly surrounds the affected text. If images have peculiar formatting demands, they will exist outside of text (Such as a CLR).
Yeah, I still have thousands of Textile pages, but all of my newer stuff is in Markdown…
As we’ve gone horizontal on tool chains instead of vertical like we used to, what you want is a bunch of mentally cheap tools with high bang for the buck. Get in, get out, move on to the next of fifty tools you have to deal with each week.
MDN documentation is written in markdown. I’ve always felt this was a resounding endorsement of markdown over other more “powerful” markup languages because if they can do it, why can’t you? (not you in particular, but anyone who thinks markdown is inadequate for docs)
https://developer.mozilla.org/en-US/docs/MDN/Writing_guideli...
I am probably in the 90th percentile of TeX users, but I have to say that it's hard for me to think that there's much space between markdown and TeX for another typesetting language. Markdown is easy to write and read but very constrained, while TeX is a bit harder and essentially infinitely flexible.
The biggest issue I have seen with TeX is a people problem: people frequently write spaghetti TeX with horrible style. This is terrible, but it is not actually a language issue. Writing it with a "docs are code" mindset can produce some very clean results. The second biggest issue is that there isn't a good TeX -> HTML compiler.
Maybe Typst (https://typst.app/) is a good in-between?
I used typst for a recent project and I love it. It’s essentially all the power of latex but with modern sensibilities. And it’s a cute little programming language - with support for variables, functions, json data loading, 3rd party libraries, and all sorts of other nice to haves.
I just wish the typst compiler had a way to output html. It would be perfect for making online documentation and blog posts.
I see typst mentions HTML output, is this only possible with something besides the the CLI? It looks very cool, going to try it out at the first opportunity.
HTML output with Typst isn't possible yet, but it has a high priority.
For the upcoming release, we decided to prioritize print layout and the shortcomings we have there. The release after (think late fall) will focus on HTML and accessible output. The plan is to create a turn-key solution for technical writing, docs, and document automation.
Indeed, I don't see the reason for someone to learn LaTex now that Typst is here.
Are you an actual LaTeX user? If so, what have you used it for that you can now use Typst for? For me, the answers are yes, and nothing.
"The second biggest issue is that there isn't a good TeX -> HTML compiler." This is the crux of the problem in using just TeX for writing books: it focuses on producing camera-ready output at the expense of literally everything else.
reStructuredText isn't itself a typesetting language. It's meant to be something of an interposer between the semantic meaning of what you're writing and the thing that does the typesetting. The hope is that it, unlike something heavily constrained like Markdown, gives you the tools to capture that semantic meaning and transform it into something that can be typeset.
Like, the goal isn't to throw out TeX. The goal is to be able to target TeX as a typesetter along with Web browsers and e-book readers and even things like GNU info and troff without having to rewrite the content wholesale to fit each one.
Personally, I would rather just have TeX itself target the web rather than wedging another layer into the typesetting stack. As far as I know, other than the sheer size of the language, there is nothing fundamental stopping someone (I guess me, eventually) from writing "htmlatex."
Modern web pages are already designed with "camera ready" in mind, essentially with browser width being the only thing that changes layout.
My point is more that TeX is a typesetter just as a Web browser is. They're incompatible typesetting systems with wildly different command languages.
I think the poster above wants to run TeX in js to format the text. I have seen a bunch of hyphenation and suchlike stretching back years not sure about running a full engine.
TeX is old and busted; Typst is the new hotness. Written in Rust, too!
"Written in Rust" matters to very few customers of your office webapp. And you should add that it is $8/month for an online platform, not free or self-hosted.
What? Typst is open source and has a CLI, it's not just an online app.
What advice do you have for writing "docs are code" LaTeX?
I find LaTeX to be the lesser of evils when creating PDFs. However, I rarely deal with LaTeX issues these days because all of the pain points have been patched away in my tooling that converts md to tex. However, I keep thinking something more modern or faster (like Typst) might make my life as an author easier. Compiling LaTeX with tools like rubber is still painful and slow.
A few things:
1. Separate each part of a document into different TeX files and include them in the main document. Each file should be a separate unit of the work. Only compile the main document when you need to.
2. Generally write with readability in mind and use newlines and other whitespace in the source a lot more than you think you should.
3. If you have common boilerplate that you frequently use at the top of docs, make your own package(s) for those commands and maintain that separately.
4. Refs and labels everywhere you possibly can. Also, prefixing your label names helps a lot, so \label{clouds} on a picture of clouds becomes \label{fig:clouds}. If you are writing a book, and this is the chapter on the sky, consider \label{fig:sky:clouds}.
Awesome. Can you point to a repository with an example?
Also, is there a book that you would recommend for learning LaTeX?
You should check out Scribble which uses Racket. It has a bunch of different renderers including HTML and Markdown. However, unlike Markdown, you can easily write extensions for it in Lisp, even within the document itself. https://docs.racket-lang.org/scribble/running.html#%28part._...
I suppose that makes it inappropriate for something like rendering comments, but it's a great way to write documents. I used it a lot for writing papers since there's a lot less boilerplate and was much easier to use than TeX.
I have used markdown to write books, and it worked just fine. Now, these were novels, not technical documents, but I never encountered something that couldn't be solved with markdown plus some occasional HTML.
I've also generated quite a bit of technical documentation using markdown, and Pandoc's extensions[1] allow you to include pretty much any formatting you might require, complicated math and syntax highlighted code blocks included.
That markdown can then be transformed into HTML, a Word doc, a ePub, a PDF ...
There needs to be a very compelling reason for me to reach for something other than markdown.
[1] https://pandoc.org/MANUAL.html
Pandoc is a great thing! However, lets not mix up Pandoc Markdown with standard Markdown. Pandoc Markdown intentionally adds features, that make it more suitable for academic writing, I believe.
Here are some Markdown books I've crafted:
* https://whitemagicsoftware.com/softcover/technical.pdf
* https://impacts.to/downloads/lowres/impacts.pdf
* https://whitemagicsoftware.com/softcover/jekyll-hyde.pdf
My blog describes shell scripts to use pandoc and knitr for converting Markdown to PDF:
https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdow...
I wrote a FOSS GUI/CLI cross-platform desktop application to replace those shell scripts:
* https://keenwrite.com
* https://keenwrite.com/screenshots.html
* https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9...
I'm using KeenWrite to write a sci-fi novel and can produce a standard manuscript format in seconds (because the content is kept separate from the presentation).
Regarding technical documentation, I extended Markdown in KeenWrite with a consistent cross-reference syntax for tables, figures, equations, etc.
* https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/ref...
Most novels don't need anything more complex than a link to the next chapter at the end of the page. Maybe bold text, but a lot get by without. As such markdown will work for most. I've seen some novels with some really complex formatting, but those are rare (I read a lot of litRPG and still call them rare). However I mostly write technical documentation and I often hit limits of things markdown cannot do even though my documents are much shorter than a novel.
To me this seems a horrible decision at the stage of writing/structuring. I'd rather write in Markdown (this way I could just write, without bothering about typesetting) and only convert to LaTeX for publishing. I'm not proficient in LaTeX though - I once tried to learn it and it felt like learning a language of an insectoid extraterrestrial civilization - completely unintuitive, almost impossible to do anything new - what hasn't been already done by someone else enabling you just copy-paste your own text. IIRC it doesn't even have first-class Unicode support.
In LaTeX you also clearly separate structure and typesetting: you don't write \noindent\textbf{Introduction}\nobreak\medskip or whatever, but simply \section{Introduction}
Macros are also pretty easy to define \newcommand\important[1]{\textcolor{red}{#1}}
And of course it has first-class Unicode support
"In LaTeX you also clearly separate structure and typesetting ..." Not quite.
The rub comes in when you want to pull that content out to render it in a format that isn't meant to be camera-ready, like a Web page or an e-book. TeX, even with Leslie Lamport's LaTeX macros, doesn't give you an ergonomic mechanism for marshalling out the semantic structure of your document to reuse elsewhere.
You're left parsing the TeX yourself, and that sucks.
Easy is relative. Latex is sooo much uglier than typst:
Docs:https://typst.app/docs/reference/foundations/function/
Uhm, reST is also easy to read and write, at least where Markdown is easy to read and write.
To me, they are largely the same thing, with slight syntax differences, with reST being more readable as it's clearer what any special syntax is about, whereas MD is more concise to type out — you need to learn the special syntax whatever way you slice it.
FWIW, reST was the default for Python "doctests": a wonderful feature that has fallen out of favour for some reason, but has the potential to be your real runnable documentation.
I wouldn't write a book in either, but that's because I am really high on great typesetting — I even had my own set of (Plain) TeX macros to do ToC generation, syntax highlighting, alternative math fonts, support for UTF-8 before eTeX and such when I did write papers and handed in coursework regularly.
It isn't though. It's just a whole lot more annoying. On paper the syntax differences are small, but they make the writing experience so much worse. I wanted to like rST but it just isn't good enough in use.
Except for native Python tools like Jupyter, which have all moved on to md.
(I still like doctests and use them extensively in my books.)
Do you really read Markdown in plain text editors? I only do occasionally (nevertheless I'm glad I can). Most of the times I use tools like Obsidian, Typora, Markdown Monster etc.
HTML is just too bad for plain source reading relatively to Markdown and too complex for reliable mapping between what it is looks, what it means and what it is.
This said, something slightly more complex than Markdown while slightly more elegant, less chaotic and more readable than HTML sounds a great thing to have.
There certainly are cases where Makrdown seems the best choice - wherever simple plaintext editors are going to be used often. Nevertheless I doubt Markdown is the best choice for tools like Obsidian - perhaps people working on new projects of this kind should also take a look at rST or AsciiDoc.
I'm with you on that, I can think of one counter example though, and that is when you have to write your MD in something like VS Code. Which uses the old-fashioned approach of source code pane and render pane. I strongly dislike that and usually try to get away with source-code view only. To be fair, they use a tiny bit of coloring, so it's not 100% plain text. And the better solution is to write your MD in any other MD editor except VSC, of course.
100 times yes. Markdown for light styling. LaTeX for anything else. The next revolution in standardized text parsers will not come from replacing Markdown, but from replacing LaTeX.
Every heard about https://typst.app/?
And it actually can be easily extended with custom blocks ( ::: ). https://github.com/vokimon/markdown-customblocks
If it was only about this, personally I find org-mode is better than markdown.
There is a big gap between a book and informal notes, docs, comments though. At least big enough to drive several tools into, or they wouldn’t exist.
Yes, that is a good rephrasing of the rest of the paragraph you quoted.
That was a rhetorical question in the article. It's immediately followed by:
Markdown has 30 different flavors because it grew organically and has no formal extension mechanism. "What am I allowed to use in this markdown processor?" never becomes an issue with reST.
That's not true, even at the basics it's not great, let alone the best: asterisks/underlines for italics already require familiarity unlike the much more intuitive /italic slashes/
And then outside the basics it's not that easy to write/read either, you'll get lost in bad formatting of tables or metadata (tags) obscuring text or what not without proper tooling
It is relevant as then you could fix those basics if you could easily and conveniently extend it
The very next paragraph in TFA agrees with you:
What do you use for the actual, non-quick documentation?
Markdown is pretty bad for note taking, it has a niche functionality suited for basic text based note taking. Unfortunately that isn’t the only note taking that is possible
yup - my knee jerk reaction at seeing the first couple of samples was to recoil. Great if it works for ppl but I'm gonna stick with markdown.
This is pretty much the paragraph that follows the paragraph you cited...
I'd go so far as to flip those two. By far, it's more important to ensure that documentation can be easily written (the raisin d'etre of MD) than it is to optimize for the job of the people trying to collate/edit/format/improve/maintain the documentation (something that RST speaks to, primarily).
Because the primarily failure mode in this space is not that we have imperfectly edited documentation. It's that we lack docs at all, because the hackers didn't understand the doc tools.
In Zephyr, we use RST. And... it's fine. I've made my peace with it. But "please write some docs" is a routine comment in review, and in my experience many-probably-most contributors just don't know how and don't want to take the time to learn. The barrier to markdown would be much, much lower.
rST and md are both not ideal for writing books. And LaTeX is even more painful. IMO using md is the lesser of two evils. I'm done kicking against the pricks with rST.