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.

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.)

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).

> it’s fantastic for chat applications

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.

  [link text](URL)

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.)

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.

  *bold*
  /italics/
  _underline_

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.

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”.

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.

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.

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.

The alternative is WYSIWYG formats that aren't plain text.

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.

    ![The Google Logo](google-logo.png)

   ![Hierarchy of the system](system-hierarchy.png)

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.

We use markdown because it is plaintext and accessible. Oh, but you have to convert it yourself. How? Well every project is different but I'm sure you can find a Makefile somewhere in the project. Good luck!

Again, the point again is that markdown is not readable alone.

If it is, then a .txt is strictly superior. If it is not, then never, ever, present it as the final product. Always ship the generated artifacts. The only point you want to actually see the .md file is if you want to make changes to it. Is making changes the primary usecase for your markdown files? I'm going to assume, no.

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).

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.

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.

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!

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

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.

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.

Modern web pages are already designed with "camera ready" in mind, essentially with browser width being the only thing that changes layout.

I just wish the typst compiler had a way to output html. It would be perfect for making online documentation and blog posts.

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 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.

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}.

I'm not sure if there is a good book on LaTeX, ironically.

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

> How easy it is to extend is largely irrelevant

It is relevant as then you could fix those basics if you could easily and conveniently extend it

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.

Macros are also pretty easy to define \newcommand\important[1]{\textcolor{red}{#1}}

And of course it has first-class Unicode support

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.

You'd want to use Typst, not LaTeX. I'm rewriting my CV with it, it's fantastic. I can now finally put the CV contents in a JSON, and generate the PDF programmatically, with lots of computed values by my own algorithms, the layout is simple, nothing stands in the way, nothing feels out of its place. And compilation is so fast... Really, forget LaTeX, embrace the 2020s.

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.

Revive Textile? It was one of the inspirations for MD, IIRC.

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.

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.

Even if rst has a generic extension mechanism, on github you'll spend a lot of time referencing commits, tags, users, pull requests and that kind of thing. So you end up having to know a domain-specific language anyway, whether it's formally presented as an extension mechanism to the language or as a dialect.

> ..Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I'm not going to begrudge anybody who avoids a tool because it's ugly.

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.

>...Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I'm not going to begrudge anybody who avoids a tool because it's ugly.

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

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.

reStructuredText (reST) by itself can be pretty rough. reST combined with Sphinx is pretty great. I.e. the strengths of Sphinx far outweigh the weaknesses of reST. For big, professional docs sites (+100 pages, +10 contributors) I have pretty strong opinions that Sphinx is probably the most responsible choice, long-term.

> The most important difference between rst and markdown is that markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree.

Yes, what this means in practice is that it's easy to customize common aspects of your site (such as how images are displayed). A teammate of mine on Pigweed recently created a shortcut for linking to bugs consistently. You type :bug:`59385981` and the link gets transformed into https://pwbug.dev/59385981. If we ever need to mass-migrate all of our bug links, it's now trivial. Another profoundly important consequence of this architecture: all internal links are guaranteed to always resolve (you get warnings/errors if you link somewhere that doesn't exist). I previously wrote about how baffling it is that this is not the industry standard for docs sites: https://technicalwriting.dev/src/link-text-automation.html

The other thing that Sphinx excels at: well-defined extension and theme APIs. It's not exactly easy to build extensions or themes, but lots of people have figured it out (including me). There's a pretty rich ecosystem of extensions and themes on PyPI.

Lately I've been calling Sphinx the sleeping giant of docs systems. It's already pretty great and with a little concerted effort I think we can collectively make it absolutely phenomenal. The upstream Sphinx repo now has a GitHub Discussions section that gets a little traffic; a lot of us seem to congregrate on the #sphinx channel in the Write The Docs Slack.

This, so much this.

It's a problem in an even more general form (for you're writing about linking to sections within a page): the number of CMS systems or static site builders that make you insert the final URL when you write is _insane_.

If the slug changes, you reorganise your site - now you have to do a search and replace through the site to update all your links.

Static site generators could enable linking like [Hello](../hello.md) and resolve the link at build time, instead of expecting everyone to type [Hello](/why/hello/). And yet the popular ones I've used or looked at don't do this.

It seems to be a marmite feature (you love it or you don't): I've raised it with static site builder team members and received a "Why would you want that?" response. Explanations got nowhere. I'm not sure if it's a niche feature, you have to have experienced the problem to appreciate the solution, or people are used to writing once and not maintaining for a decade or longer, but it'd be great to see wider support.

I'm not a fan of reStructuredText, but nowadays it's possible to do most things that previously tightly coupled Sphinx to RST in Markdown, courtesy of MyST-Parser: https://github.com/executablebooks/MyST-Parser

I found this to be very easy using Markdown+pandoc. I turned image tags containing youtube links to thumbnails with video tag and alt text, hooked up image tags to local video files to ffmpeg to optimize and resize videos to then do the same, etc in a few lines of code.

However I'd push back a little. That Fluent UI doc site looks like every other doc site from an open source project started since ~2020 that I've seen, and this means that I have certain expectations: I expect the project to be immature, I expect the docs to be incomplete or out of date, I expect the search to be an annoying AI search that does a worse job than the basic full text search that I expect elsewhere, I expect that to get anything of substance done I'm going to have to hang out on a Discord server. When I see a ReadTheDocs site though with that default theme, I expect the project to be somewhat mature, I expect it to basically work. I expect the docs to be fairly complete.

Are these expectations fair? Not really, but that's the whole point here. Open Source projects are not immune from marketing, and when marketing, what other similar projects do will affect how people respond to your marketing. Nothing exists in isolation.

In my experience, engineers think marketing doesn't apply to them, but these impressions really do matter.

One nit: I called Sphinx a sleeping giant because it's already majorly successful in the Python ecosystem. Pretty much all big Python docs sites are built on top of Sphinx, including docs.python.org. But I think it's fair to say that when Sphinx starts getting major adoption outside of the Python ecosystem then we can start calling it a breakout success.

I'll ignore Apple because: 1) It loads _extremely_ slowly (10+ seconds). 2) Just looks like a dark theme and nothing more.

The featured themes, in general, have poor typography and whitespace, poor formatting and alignment, and uninspired colors and design. Furo [0] is the best-designed of them and would make a solid foundation for a proper theme.

[0]: https://sphinxthemes.com/themes/furo

[1] https://pigweed.dev/#what-is-pigweed

The first part didn't really do it for me because it seemed too meta:

"Over 150 libraries" - to do what? (Actually, some good examples are in the next section.) "Automation" - to build, test, and lint what? "Environments" - to make builds reproducible, to do what? "Frameworks" - turnkey solutions for what?

They are clickable, though, so maybe I should have clicked. :)

> We provide libraries (modules) for strings, time, assertions, logging, serial communication, remote procedure calls (RPC), and much more.

Maybe put that up front?

Looks like "frameworks" are still work in progress; maybe I'll check back someday when they get to Raspberry Pi Pico support.

At my last job I spent a fair amount of time on documentation, but I don't have a great understanding of what technical writers like/dislike, or what documentation systems are best.

So, you've made a convincing argument of why we should prefer Markdown to reST, 9 times out of 10. If we're working with Sphinx we'll give it serious consideration.

So yeah, I don't really have strong opinions on sticking with rest per so. I only have strong opinions about Sphinx being probably the best choice out there for large docs sites.

[1] https://myst-parser.readthedocs.io/en/latest/

This is my main problem with the article, as this is decidedly incorrect.

Markdown was designed as a tool of conversion of de facto standard of formatting text in email messages and Usenet posts of early nineties. The basic 7-bit ASCII nature of those technologies inspired people to informally annotate the text with special signs to denote formatting like emphasis, section titles and the like.

True, HTML shares a lot of similarities with that nameless standard, so John Gruber in 2004 wrote a basic script [0] to convert the latter to the former, never expecting it to become such a universally used actual standard.

[0] https://daringfireball.net/projects/markdown/

Gruber did not take a "de facto standard" from Usenet and simply write an HTML converter for it. He designed his own markup, borrowing from Usenet and other conventions. The “Acknowledgements” section at the bottom of your link alludes to this fact.

Markdown was from the beginning intended as a markup syntax for web CMSs. To say it is a lightweight representation of HTML is correct. The whole point was that every part of the syntax produce a direct HTML equivalent.

> To say it is a lightweight representation of HTML is correct.

It's correct in the context of (2) but not (1). In the context of (1), Markdown is a lightweight markup language for rich text. For example, Pandoc can convert Markdown to formats like PDF, LaTeX, and ePub.

This is made abundantly clear on the Syntax page[0]:

> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

> Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

> For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Markdown is very coupled to HTML, and is hobbled as a result compared to formats like Tiddlywiki and Org that not only have sophisticated syntax for all kinds of content like tables, but also directives to the parser itself to render particular blocks using an external tool. I wrote a bit about this in 2021 in response to query about why Org mode doesn't use Markdown[1].

[0]: https://daringfireball.net/projects/markdown/syntax

[1]: https://rpdillon.net/why-doesnt-emacs-org-mode-just-use-mark...

As a matter of history you're right, just as JSON was intended as nothing more than the literal syntax for JavaScript programs. But it turned out to be a lot more widely applicable.

> To say it is a lightweight representation of HTML is correct.

No, it's a representation of writing. It represents the input not the output.

The fact that Markdown was inspired by email conventions doesn't make the statement "markdown is a lightweight representation of html" any less correct.

You can read a Markdown document pretty easily using "less" or any other character-based interface.

The same is not really true of reST.

Maybe I'm confusing that with some other plain-text markup convention?

this is clear from the fact that HTML can be inlined in a markdown document; this is part of the spec (in so much as there even is a "spec" for markdown, anyway).

Some Markdown parsers support some HTML. You cannot, for example, add a YouTube video embed to a GitHub comment. Webpages that allow Markdown quite reasonably limit what’s accepted.

> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Both Gruber's original and CommonMark (the closest thing to a standard) support inline HTML.

Both Gruber and CommonMark specs are defined in terms of its HTML output.

On this question, it isn't.

Markdown qua Markdown, unambiguously supports HTML tags. You can verify that yourself: https://daringfireball.net/projects/markdown/

The introduction being:

> Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

It's not possible to read the original specification without agreeing that, yes, Markdown is specifically a way to generate HTML. It also has a nice syntax which has become popular in contexts where embedding HTML isn't a good idea, and there are some tools which allow Markdown to be converted to other formats as well (usually, but not always, these disallow most HTML tags, meaning that they aren't Markdown sensu stricto either).

I would say that all of this supports Hillel's basic point here: Markdown is in fact tied to HTML semantics, in a way which makes it painful to do things with it which aren't tied to those semantics in the same way. Dialects in the Markdown family exist which make this less painful, and they do so by diverging from the original Markdown spec.

The section I quoted (and responded to) didn’t say “Markdown supports HTML tags”, it said (emphasis added) “Markdown parsers support (…)”.

So unless you’re arguing that a tool cannot be considered a true Markdown parser¹ unless it parses HTML, the distinction is irrelevant. I wasn’t making a general argument, I was responding to a specific claim.

> You can verify that yourself

Yes, I am quite familiar with that subpar piece of code and specification. I have spent some time implementing a Markdown parser myself (the output wasn’t HTML) and Gruber’s resources were by far the worst. For various reasons he has been an awful steward of Markdown; its ubiquity is despite him, not because of. Forgive me if I don’t find the author to be the authoritative source anymore.

¹ https://en.wikipedia.org/wiki/No_true_Scotsman

> Markdown was designed…

Surely Gruber is an authority on that.

And anyway, “ markdown is a lightweight representation of html” is true enough that calling it “decidedly incorrect” is wrong. Certainly it’s not a point that’s supported by going to author intent.

Yes, I completely agree with that.

And that wasn’t the point I quoted or responded to.

> From the top comment

Again, I wasn’t replying to the top comment, I was replying to what I quoted, from the comment I replied to.

- Please respond to the strongest plausible interpretation of what someone says, not a weaker one that's easier to criticize. Assume good faith.

- Please don't pick the most provocative thing in an article or post to complain about in the thread. Find something interesting to respond to instead.

https://news.ycombinator.com/newsguidelines.html

If you disagree with the substance of the article, say you prefer Markdown to rST, then address that. Explain why despite the author's preference for rST, you prefer MD. It's silly to argue over this single sentence about exactly what Markdown is or isn't.

You seem to have a very peculiar interpretation of the word "connection"

> and is quite incompatible with them.

It can't be incompatible with ad-hoc unspecified and informal formatting habits.

> Perhaps my intent would be more clearly expressed by inverting it: email formatting has nothing to do with Markdown.

That's just as inane for the same reasons.

    * one
    * two
    * buckle my shoe

    | inspiring quote
    | - some famous guy

    foo
        a kind of bar
    bar
        part of a foo

    :red: stop
    :yellow: speed up
    :green: go

    - code:: python

    def fun():
        pass

    Go here_ for more info.
    - :: here: https://google.com

    My **strong** text is well *emphasized*. Very ``literally``.

Two problems I had were: (1) common with a lot of systems, the RST tools don't contain an RST unparser. I really wanted to be able to generate RST files automatically by merging content from other RST files and other sources and working with them via a document API. The RST tools don't support that. (2) The RST tools expect a certain defined set of blocks for a particular document; it would be very possible for a system to represent blocks in a generic way which would make possible tools that can transform documents without necessarily knowing the definitions of blocks inside it.

These are problems w/ the tools, not problems with RST itself but every time I'm forced to strip my code back to the walls is an opportunity to think about some other markup system such as something HTML-based.

Instead of HTML you can use XML to write structured documents. With XML you can define whatever custom tags you need with schema validation if desired. The advantage of this approach is you have full control over the input schema and output, but the downside is XML is much more syntactically noisy compared to Markdown or RST and you will need a script to parse & convert the XML to your preferred output format(s).

- is a superset of XML (XML is derived from SGML as a simplified, proper subset)

- can parse HTML precisely with all bells and whistles such as tag omission, enumerated attributes and other shortforms (which are based on SGML after all)

- can define markdown syntax as an SGML SHORTREF customization (note that SGML can not cover all of markdown syntax; for example, defining reference links somewhere at the end of a document and expecting SGML to pull a href URL into the place where the link is referenced won't work with SGML SHORTREF)

The combination of markdown-as-sgml and inline HTML or HTML blocks is particularly nice and predictable, and also informs further customization such as using entities (text variables), custom elements, and other advanced SGML stuff with markdown that comes up frequently as a requirement.

That is, XSLT is based on pattern matching rules that most people find strange and unfamiliar. It wouldn't be so strange to people if this kind of system was more widespread, but as an island that's different from everything else I think people struggle to wrap their heads around it.

XSLT will happily output any number of formats from an XML doc. There's also a number of existing and very capable XML schemas for documentation like DocBook. You can even go from a lightweight markup like RST or Markdown to DocBook and then have an XSLT pipeline that delivers that intermediary to any number of formats. There's also very capable graphical editors that will spit out DocBook directly.

I find the aversion to XML very strange. It was definitely applied in some places poorly by products with "Enterprise" somewhere in the name but the language itself is very useful. The aversion to XML has led to a lot of work re-learning of the lessons that led to some XML features. It's also led to implementing XML features poorly in other languages.

Loads of other systems I work with still output XML, and I have fast, powerful tools to work with them pre-installed on any Mac I work on, and it doesn't even matter that Apple hasn't updated them in a while since XML hasn't really been changed either. I can look at an XML doc and have so much information about the data inside just telegraphed into my head, just by the way the things are shaped. I don't have to read the tags like a book, I can just gloss over them and still get enough to understand the strings/numbers inside. Yet, they're still on the page, out of focus, in my periphery, providing anchoring and structure and navigation, I can find my place. Maybe I'm just a freak, or that comes from 20 years of staring at them. Whatever reason, I just can't do that with JSON as easily or as fast.

I don't hate on any of the other formats (save for YAML, not interested), and I really appreciate JSON's brevity sometimes for simple data and small responses, but that brevity quickly turns into wisps of formatting and text seemingly floating out in the middle of nowhere.

Same. Every back end project I work on I recommend XML as the transport and every time I get a reflexive "ugh, XML". Then I spend an inordinate amount of time making Swagger endpoints so a consumer can figure out how the JSON output is supposed to behave.

It really isn't. Both namespaces and schema cause far more problems than they solve. And the theoretical advantages of having a declarative language for expressing transformations (and schema) is outweighed by how awful it actually is to write XSLT (and schema).

If we had namespaces for classes and id's in CSS we'd be able to transclude content from one HTML to another HTML page easily but we don't so we can't. (Shadow DOM helps a bit though) The "hygenic macro problem" is one of the many barriers people face doing metaprogramming. In the RDF world it's refreshing to be able to import facts from multiple systems into multiple namespaces so you can put data you got from different sources into the same database and "it just works".

I don't think namespaces solve the macro hygiene problem, because if you're going to have macros then they need to be able to interact with and manipulate your namespaces, and sooner or later you need your macro to e.g. generate a fresh identifier for use within an existing namespace and then you're right back where you started.

Being able to disambiguate when you have one document including another would be useful. But the cost/benefit on XML-style big namespacing up-front just doesn't stack up.

If it had that it would be a 200 foot tall giant robot, as it is it's just another documentation generator.

To me, the whole point of markdown is to allow you to do simple things faster than writing raw HTML, but with the ability to intersperse raw HTML when needed.

In projects where I've needed the power of RST over markdown, I've felt more comfortable just writing raw HTML directly.

> This means you can extend Sphinx with new text objects! Say you that instead of an , you want a

    # state class to contain the counter
    class _spoiler:
        count = defaultdict(lambda: 0)
    
        def id(src):
            _spoiler.count[src] += 1
            src_hash = sha256(src.encode()).hexdigest()[:7]
            return f'spoil-{src_hash}{_spoiler.count[src]:03}'
    
    def spoiler_role(name, rawtext, text, lineno, inliner,
                     options={}, content=[]):
        src = inliner.document.attributes['source']
        html = (
            ''+\
            '{text}'
        ).format(text=text, id=_spoiler.id(src))
        return [nodes.raw('', html, format='html')], []

1. HTML is designed for representing webpages, not books. Your intermediate representation will become HTML's DOM, which is likely not well suited to the book use case. You'll either need to use an existing HTML-to-DOM parser or build your own. One big limitation of the DOM, as I see it, is that it doesn't have the concept of a page number.

2. HTML is not extensible in the way the author talks about. This is the "semantic linking" thing I meant. In rST, you can define entirely new top-level constructs: he defines an exercise which has a solution and will be a part of a solution list. The semantic linking part is that other parts of the document will refer back to these solutions. Some output formats will have all solutions inline, with the exercises, while other output formats will collect all solutions in one place at the end. HTML is not flexible in that manner.

What is extensible is XML. It's entirely feasible for XML to be the input, but for better-or-worse, most people are even more turned off by XML than they are by something like rST.

The point is that it's objectively better when you want to separate the concerns of writing content and rendering it. It makes writing much easier and keeping the layout consistent as well.

The real gamechanger is for internal links (rST+Sphinx) and the use of the `:ref:` and `:doc:` directives so that you can reference an anchor or a doc link in the same content without having to type the header manually (which will inevitably go stale).

https://www.sphinx-doc.org/en/master/usage/referencing.html#...

that is one of the things I miss most about writing in rST, for sure.

GitHub’s own docs for project pages don’t work. Do I need a .nojekyl file, are gh-pages branches still required? Is there a config error in the repo or did changes just not prop? I guess I’ll try actions. Fast forward a few hours and this is getting unreasonable, haven’t looked at read the docs in a while, let’s see if that works. Ok it’s being weird and wants sphinx maybe, let’s get sphinx to work with markdown, ok cool. The build works but the page width is broken after deployment even though I can’t reproduce on my machine so it must be the ads injection on the community tier.

I know all this is working fine for lots of projects and have done it myself in the past. It works after it’s working. But it’s all so unbelievably fiddly. Bottom line, Markdown vs Rst isn’t even a choice/pain point on my radar, it’s more down to finding that good fit for medium sized docs projects / static hosting.

For hosting static sites, I actually like AWS amplify, and integrating it with github seems currently easier and certainly more flexible than trying to use github pages. But I don't really want the hassle of a custom domain or a subdir on existing inappropriate domains for every new project I start.

This isn't about being cheap either BTW, I think it's important that self-hosting should NOT be the best way to get a friction-free setup for small-to-medium sized project docs. There's a major benefit just to the recognizable domains for github-pages / readthedocs, which is that I know I'm about to look at some kind of technical project documentation that is most likely a labor of love, rather than marketing fluff or a "sign up for the preview here!" bait and switch.

    #include 

Speaking as one who actually produces blogs on rare occasions, I have to say starting every post with "This is just my experience and may not apply to you this is not a claim of global applicability this is just applicable to this circumstance you're the one who chose to read this I didn't force you" and so on isn't exactly the most compelling way to open a post.

Though I have to admit now I'm really tempted to add that into my post template in like 2pt font or something, just so when people on HN complain I can point them at it.

By contrast, I was careful to criticize the title as clickbait, not the post, which is useful (or the book, which sounds genuinely interesting). I wasn't perturbed by the title. By your comments, sure, but that's your doing, not Hillel's.

"Why I prefer rST to Markdown"

or

"Why I prefer rST to Markdown for Typesetting"

Since it's a clearer statement of the author's meaning, and since very few users interested in Markdown are going to be doing any typesetting, it seems like a more meaningful title to me.

But less likely to draw in readers... to "bait" them, if you will.

They've got extremely similar goals, and for the most basic text, both read and write like plain text too. And it was obviously a time when this thing simply became a thing everybody desired, so many "formats" appeared.

Why did MD win has — IMO — nothing to do with how it's "simpler" or "more readable" — they are largely interchangeable for anything that's easily represented with whitespaces in pure ASCII.

Or does someone claim that the following is unreadable gibberish that they need a parser for?

  The best friends
  ================

  ``markdown`` and ``reST`` are two formats that *largely* aim to achieve the same goals:

  * Be simple to read without any parser
  * Be quick and simple to type out

reST offers a lot of additional formatting features which are beneficial if you need them and cruft when you don't.

I first started using Github-flavored Markdown after signing up for Github in 2010 (possibly earlier under another alias.) I used reStructuredText for Python docs a couple times. I found the latter to have a much higher learning curve and I haven't had a reason to use it since.

But looking through examples at https://docutils.sourceforge.io/docs/user/rst/quickref.html#..., I really see a lot of non-simple stuff done in an obvious way too (block quotes, tables, bullet and enumerated lists, sections and headings, separator lines...).

By the time you got on the markdown train, it has already won out, and you've probably seen a lot more of it than of reST, even if MD still wasn't standardized. As a counter-point, having done lots of reST with Python docutils prior to 2010, I still mix up reST and MD — there's nothing intuitive about any of their special syntax, and our perception is mostly tainted with our prior experience. I've also written a lot of ASCII-only docs prior to either of those, and most people used ever-so-slightly different conventions there as well (somebody mentioned using /this/ for italics as well).

reST was standardized in the form of a Python PEP from its inception so you could at least rely on learning it once.

Edit: My ultimate point is that you (and most everybody else, including me) are using MD because it's more popular, not because it's "better".

I agree that reST is probably a better fit for complex use cases like building a docs site. But it's overkill for Facebook Messenger or even forum posts, IMO.

If you want to use a mark-up language in a chat app, a subset of either would serve you just fine and both are equally simple. It sounds like you are comparing a subset of what-is-markdown-today (and there are still variants) to full reST, which I don't think is a fair comparison.

From a very brief look, here's some things that probably aren't generally necessary (and aren't included in Markdown): Document structure, Bibliographic fields, complex footnotes and citations, directives, substitution definitions

All of these increase the number of things I have to escape, as well as my cognitive load when writing documents. And that's before we talk about reST config settings!

You could use a subset of reST, or you could just use Markdown!

Unreadable? No. Frustrating to type out? Yes. Underline style is annoying when editing, and even if you technically don't have to match the length you will still feel obliged do. Double backtick is just awful to write, annoying out of all proportion to how much extra time it actually takes.

I still wouldn't go as far to say the MD or RST syntax is hard in any way (and really, asterisk which requires a Shift key is worse than double backticks).

We had our documentation in asciidoc and it was awesome to write. We migrated to RTD/Sphinx/rST mainly for 1) better handling of i18n and 2) better handling of multiple-version-documentation (switching between versions)... and I loath rST every day. It's syntax is just abysmally awful and the tooling sucks (seriously, it's not just bad... it sucks!).

Nowadays there is antora but still - i18n is still a problem…

And markdown - as a simple tool to add some simple and basic formatting is just awesome and it's easily readable even if you don't have parser and end up having to read plaintext…

But at the same time, I find the writing experience for more advanced stuff too poor. The author talks about references, but do we have a language server that can look up available references, headlines, figure names etc and help you auto complete?

That’s what would make me take the plunge to a more advanced system.

That would be a total gamechanger! Having the ability to do ref/doc links and not have to worry about stale topic headers is another thing I loved about writing in rST that I miss now that I'm back in markdown.

    ![alttext](example.jpg)

    .. image:: example.jpg
      :alt: alttext

    ... you can extend Sphinx with new text objects!
    Say you that instead of an , you want
    a 
 with a 

        ![alttext](example.jpg)[caption]

I guess this sort of falls under the "But I hate the syntax" section of the article, but I don't think it quite gets the point. I can look at a Markdown file and read or write it without even really thinking. Which is not really the case with rST (or even HTML, for that matter).