return to table of content

I prefer rST to Markdown

Arainach
94 replies
1d

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.

bityard
47 replies
1d

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

keybored
16 replies
23h35m

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

deathanatos
8 replies
16h29m

3. Many then implement it with or without edge cases

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

m-p-3
3 replies
16h22m

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.

pitaj
1 replies
2h53m

I think one of Markdown's biggest mistake was making `*` and `_` interchangeable. It should have been `*bold*` and `_italics_` from the beginning.

m-p-3
0 replies
2h41m

I agree with you on that.

What about * for bold, / for italic and _ for underline?

deathanatos
0 replies
16h5m

Way back in the day when I was on IRC, I usually read them as,

  *bold*
  /italics/
  _underline_
… 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.

keybored
2 replies
7h13m

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.

Zacru
1 replies
4h19m

having it in the raw form while typing

This is actually an option in the settings (on desktop, at least).

keybored
0 replies
4h9m

Aw that’s embarrassing. Thanks.

fragmede
0 replies
14h18m

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.

cqqxo4zV46cp
2 replies
18h35m

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.

KerrAvon
1 replies
17h1m

But nobody (relatively speaking) uses CommonMark, and everyone uses Markdown

input_sh
0 replies
2h0m

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.

strken
1 replies
15h49m

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

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.

keybored
0 replies
7h16m

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

bitwize
0 replies
21h1m

Markdown is the Unix of rich text formats.

billti
0 replies
17h41m

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.

tetha
9 replies
1d

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.

zelphirkalt
2 replies
21h57m

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.

lmm
0 replies
19h5m

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.

fireflash38
0 replies
21h40m

Agreed. Mandate function docstrings? You'll get "Function FlargleBlab blabs the flargle" docstrings. Just useless.

unethical_ban
2 replies
23h14m

Yes!

Markdown is great because it is a way to write and store documentation in plaintext, in a way non-documentarians can follow.

duskwuff
1 replies
21h57m

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

eru
0 replies
14h35m

Yes, though I would expect most news-folks to use some form of WYSIWYG for writing?

runlevel1
2 replies
17h11m

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.

AndIHateLatex
1 replies
16h49m

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?

eru
0 replies
14h36m

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

packetlost
9 replies
1d

But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.

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.

paholg
8 replies
23h56m

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

steveklabnik
6 replies
23h41m

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.

paholg
5 replies
22h38m

Ah, good to know! Is that tooling public anywhere, or was it pretty tailor-made just for the Rust book?

paholg
1 replies
22h23m

Awesome! You and Carol rock!

steveklabnik
0 replies
21h44m

Thanks! She gets 100% of the credit in this case though :)

brnt
1 replies
10h26m

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!

steveklabnik
0 replies
3h17m

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!

tjoff
6 replies
22h2m

Markdown is about a bare-minimum amount of styling that is just as readable and at home in plaintext as formatted in HTML.

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.

8organicbits
5 replies
20h49m

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.

tjoff
4 replies
20h23m

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.

8organicbits
3 replies
19h44m

There's no reason for this to be all or nothing. This seems perfectly readable to me:

    ![The Google Logo](google-logo.png)
Even if you've never seen markdown before, it's pretty obvious.

tjoff
1 replies
11h57m

How often do you refer to the logo? Try something like this:

   ![Hierarchy of the system](system-hierarchy.png)
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.

8organicbits
0 replies
33m

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.

AndIHateLatex
0 replies
16h39m

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

rcarmo
0 replies
23h15m

Yeah, I still have thousands of Textile pages, but all of my newer stuff is in Markdown…

hinkley
0 replies
23h10m

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.

SPBS
0 replies
6m

But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.

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

pclmulqdq
18 replies
1d

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.

conaclos
6 replies
21h59m

Maybe Typst (https://typst.app/) is a good in-between?

josephg
3 replies
21h40m

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.

enema_bag_jones
1 replies
17h26m

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.

flokl
0 replies
12h33m

HTML output with Typst isn't possible yet, but it has a high priority.

reknih
0 replies
10h26m

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.

g8oz
1 replies
20h38m

Indeed, I don't see the reason for someone to learn LaTex now that Typst is here.

auggierose
0 replies
1h48m

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.

nrr
3 replies
21h57m

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

pclmulqdq
2 replies
21h3m

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.

nrr
1 replies
20h43m

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.

justincormack
0 replies
17h28m

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.

bitwize
2 replies
20h38m

TeX is old and busted; Typst is the new hotness. Written in Rust, too!

pclmulqdq
1 replies
6h17m

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

bitwize
0 replies
39m

What? Typst is open source and has a CLI, it's not just an online app.

__mharrison__
2 replies
17h57m

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.

pclmulqdq
1 replies
6h18m

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

__mharrison__
0 replies
5h25m

Awesome. Can you point to a repository with an example?

Also, is there a book that you would recommend for learning LaTeX?

slaymaker1907
0 replies
1d

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.

thomascgalvin
3 replies
1d

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

zelphirkalt
0 replies
21h50m

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.

thangalin
0 replies
18h20m

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

bluGill
0 replies
23h57m

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.

qwerty456127
3 replies
23h25m

I don't want to write a book. If I did I'd use LaTeX before RST.

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.

anserin
2 replies
22h55m

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

nrr
0 replies
21h12m

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

necovek
2 replies
22h0m

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.

lmm
0 replies
18h58m

reST is also easy to read and write, at least where Markdown is easy to read and write.

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.

__mharrison__
0 replies
17h55m

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

qwerty456127
1 replies
23h28m

Because the biggest advantage of Markdown is that it's easy to read

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.

riidom
0 replies
22h18m

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.

philistine
1 replies
23h39m

I don't want to write a book. If I did I'd use LaTeX before RST.

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.

ska
0 replies
1h25m

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.

ori_b
0 replies
23h20m

Yes, that is a good rephrasing of the rest of the paragraph you quoted.

makeitshine
0 replies
19h2m

That was a rhetorical question in the article. It's immediately followed by:

..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.
kevin_thibedeau
0 replies
16h56m

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.

eviks
0 replies
22h6m

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.

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

edgarvaldes
0 replies
1d

The very next paragraph in TFA agrees with you:

...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.
bosie
0 replies
21h59m

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

bilater
0 replies
1d

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.

andrepd
0 replies
21h49m

This is pretty much the paragraph that follows the paragraph you cited...

ajross
0 replies
1d

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.

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.

__mharrison__
0 replies
18h2m

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.

BerislavLopac
28 replies
1d2h

markdown is a lightweight representation of html

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/

simonw
12 replies
1d2h

I disagree. Markdown has always been about HTML - to the point that Markdown parsers support dropping actual HTML tags mixed in the the markup.

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

latexr
7 replies
1d1h

to the point that Markdown parsers support dropping actual HTML tags mixed in the the markup.

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.

samatman
3 replies
1d1h

Usually, the colloquial conflation of Markdown with CommonMark and the numerous Markdown-esque dialects is helpful language, I've defended it here before.

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.

latexr
2 replies
1d

Markdown qua Markdown, unambiguously supports HTML tags.

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

travisjungroth
1 replies
1d

I think you’ve kinda lost the thread. From the top comment:

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.

latexr
0 replies
23h59m

And anyway, “ markdown is a lightweight representation of html” is true enough that calling it “decidedly incorrect” is wrong.

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.

The_Colonel
2 replies
1d

Gruber:

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.

latexr
1 replies
1d

Yes, that’s why I said “some”. I don’t understand what’s ambiguous about that.

The_Colonel
0 replies
14h13m

The question is whether these are even Markdown implementations, or rather something like "Markdown-like format".

SoftTalker
3 replies
1d1h

I thought a goal of Markdown was to be a set of conventions that were readable on their own as well as being transformable to a rich text/HTML representation.

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?

woodrowbarlow
0 replies
1d

all of that is true, but markdown targets HTML as its "native backend", if you will. it is not feasible to render markdown -> pdf without having an intermediate HTML representation.

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

paiute
0 replies
1d1h

The article convinced me that markdown is better for its purpose.

Spivak
0 replies
1d

reST is also designed to have human readable source. You might not like it compared to markdown but it has to serve as a the docstring format of Python and does so fairly well.

velcrovan
6 replies
1d2h

The very first sentence in that link says “Markdown is a text-to-HTML conversion tool for web writers.”

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.

CharlesW
4 replies
1d1h

Gruber writes that Markdown is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.

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.

The_Colonel
2 replies
1d1h

Isn't inline HTML valid within Markdown? You could say that Markdown is a superset of HTML.

NekkoDroid
0 replies
2h9m

It depends on the dialect you are using. Some support a limited subset of HTML, some allow all and some allow none (maybe HTML/XML comments).

rpdillon
0 replies
1d1h

It's also true in the context of (1), since the syntax specification specifically falls back to HTML for difficult things like tables.

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

lmm
0 replies
16h15m

Markdown was from the beginning intended as a markup syntax for web CMSs.

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.

chrismorgan
3 replies
1d1h

Markdown, Markdown, is nothing to do with email and Usenet formatting. It was a specific syntax, poorly defined, which has since become a broad family of mostly similar syntaxes; and it was inspired by various conventions from things like email and Usenet, some of which predate computers (e.g. pretty sure I’ve seen or heard of asterisks being used for italics in old typewritten stuff); but Markdown is all about HTML, its syntax is extremely constrained by HTML, and any attempts to separate it from HTML are fairly thoroughly doomed.

masklinn
2 replies
1d1h

Saying that it has nothing to do with email/usenet is a bridge too far in the other direction, it was very much inspired by such formatting, something it never hid: https://daringfireball.net/projects/markdown/

the single biggest source of inspiration for Markdown’s syntax is the format of plain text email
chrismorgan
1 replies
1d1h

Yeah, it was inspired by those things, as I said, but it was never connected to them, and is quite incompatible with them.

I also express things that strongly because I’ve observed a distinct tendency to interpret Markdown as the successor of those things or the inventor of such syntax ideas. Whereas in fact, Markdown was not the first lightweight markup language, and is not the only one, and isn’t even the LML unquestionably closest to plaintext email conventions (reStructuredText is an obvious contender; overall, I’d consider reStructuredText a little closer than Markdown, but it’s subjective).

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

masklinn
0 replies
1d

Yeah, it was inspired by those things, as I said, but it was never connected to them

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.

tombert
1 replies
1d

Yeah, that's what I feel gives markdown an edge over nearly anything else; markdown is adopting conventions that were meant to be readable without any kind of rendering. I can very easily tell what my markdown document is going to look like before I render it with Pandoc, because it's basically just taking stuff people were using with plain text that was meant to be read directly anyway.

I haven't used rST, but looking at the examples it looks considerably less readable out of the box.

Spivak
0 replies
1d

Oh it's not that bad.

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

keybored
0 replies
1d1h

You’re both right. The original implementation was a superset of HTML. Do the lightweight syntax for the common stuff and HTML for the rest.

js2
0 replies
1d

Dear HN: stop leaving comments like this. It's arguing over semantics and makes for boring conversation. It also violates HN guidelines for leaving comments:

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

kaycebasques
23 replies
1d1h

Context: I've been a technical writer for ~12 years. I actually started out my career migrating a startup's docs from Word to Sphinx. Then I did a lot of time on Google's proprietary CMS/platform for developer docs. Then a few years on Eleventy-based sites. For the last two years I've been back on a Sphinx-based site (pigweed.dev). I've also done some odd jobs for readme.com-based startups and have dabbled in Docusaurus, Astro, and Hugo.

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.

dlivingston
4 replies
22h15m

If you want Sphinx to achieve that breakout success, priority #1 should be to get high-quality, beautiful themes.

At least for me, aesthetics are a high-priority factor when deciding which site generator to use. Hugo and Gatsby have great built-in themes, and I have chosen them for projects before based largely on this fact.

The Sphinx themes here [0] and here [1] are various levels of "meh" to bland.

Look at the standard Sphinx RTD theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/

Now, compare it to documentation sites like:

- Apple's: https://developer.apple.com/documentation/swift/array

- Fluent UI: https://react.fluentui.dev/?path=/docs/concepts-developer-po...

RTD looks dated in comparison.

[0]: https://sphinx-themes.org/

[1]: https://sphinxthemes.com/#featured-themes

0xedd
1 replies
21h7m

Looking at Fluent UI VS featured-themes, I don't see a difference.

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

dlivingston
0 replies
20h58m

Apple's site loads for me in under 1 second with a clean cache force-reload.

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

kaycebasques
0 replies
17h5m

I agree that more stellar, super-visually-appealing themes will help Sphinx get to the next level.

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.

danpalmer
0 replies
17h21m

I don't disagree that themes are an important part of marketing a tool. The engineer in me doesn't want that to be the case, but I recognise that people like pretty things, it makes a difference.

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.

einpoklum
3 replies
1d

reStructuredText (reST) by itself can be pretty rough. reST combined with Sphinx is pretty great.

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.

Spivak
1 replies
1d

I'm not really sure what your point is. What you're saying agrees with both the parent and the OP.

einpoklum
0 replies
21h57m

My point is that the reason GP prefers rST is a reason not to prefer it, usually.

kaycebasques
0 replies
16h58m

I heard recently that MyST [1] now has full feature parity with everything that reST provides. If I were starting a new project today I would seriously look into Markdown-based Sphinx site powered through MyST. For Pigweed we collectively don't seem to hate reST enough to justify the huge project of migrating everything over from reST to Markdown.

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/

skybrian
2 replies
1d

Some drive-by feedback on pigweed.dev: It seems like it’s missing a “What is Pigweed” section? I was wondering what Pigweed does and eventually found the Github README, which is somewhat better. (I’ve used Arduino, but I’m not quite sure what I’m looking at.)

kaycebasques
1 replies
17h11m

Thanks. It's basically middleware for large, professional embedded development teams creating mass market products, usually consumer electronics. The four pillars in the "What is Pigweed?" section on the homepage [1] really do sum up a lot of what we do, but the reality is that it's a difficult "product" to explain in general. But rest assured that it's definitely on my radar that there is huge room for improvement in our "What is Pigweed?" content.

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

skybrian
0 replies
16h33m

Apparently I'm bad at skimming. I did see that section, though apparently not the heading :)

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.

shepherdjerred
2 replies
1d

Why do you like Sphinx so much? Have you ever used MkDocs/Material for MkDocs? How do they compare?

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.

irskep
0 replies
19h27m

I've used both extensively. (Material for) MkDocs is easy to set up and gives very good UX for users. Sphinx is hard to set up and provides better UX in some ways (internal links are on another level entirely), and worse UX in others (the themes are all worse than Material for MkDocs, every single one).

bluGill
0 replies
1d

I like sphinx because I can make it do all the weird links between documents that I want. Markdown can't do that. I've never used MkDocs so I cannot comment.

throw310822
1 replies
23h6m

Ok, what about DITA?

kaycebasques
0 replies
17h1m

Also very powerful. Haven't worked with it in years; need to revisit.

ak217
1 replies
1d1h

Agreed that Sphinx is extraordinary and wildly underrated. Sphinx is the only architecturally sound, extensible, widely used documentation framework that I know of. Its plugin ecosystem is amazing and gives me incredible leverage to improve documentation for teams and projects.

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

bluGill
0 replies
1d

Except that the plugins are not compatible with each other or the latest version. That means I'm seeing some bugs that are fixed in the latest but I can't get the fix because my doxygen plugin doesn't work with the latest, and even if it did is the mermaid plugin updated yet? (please don't ask which versions of each I'm using - I believe there are at least 2 different ones that can do both of the above and they all have different abilities...)

pbowyer
0 replies
23h59m

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

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.

mixmastamyk
0 replies
22h19m

I liked it as well. But many years ago I tried to get them to implement parts of a book, and they never did. You can work around somewhat by hardcoding chapter numbers—but I don’t feel sphinx is suitable for book-length docs without that simple feature.

eska
0 replies
1d

Yes, what this means in practice is that it's easy to customize common aspects of your site (such as how images are displayed).

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.

__mharrison__
0 replies
17h54m

Until you need to make a physical book with Sphinx or write custom tooling with it...

PaulHoule
22 replies
1d2h

I was looking at RST as an answer for a documentation system with similar complexity to the system he's building and an intense need to mark stuff up with definite semantics, both in the case of capturing structures in the RST file in a database and mixing database results into the content.

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.

hgs3
12 replies
1d2h

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

giantrobot
6 replies
1d1h

Markdown or RST and you will need a script to parse & convert the XML to your preferred output format(s).

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.

wpm
1 replies
22h10m

You're not alone. I find XML to be massively more readable and flexible. I work in the macOS/iOS IT space, and our bread and butter is the Property List, which tends to either actually be XML underneath or is at the very least rendered like XML, all just conforming to the plist DTD (which is pretty short). These plists that conform to this fairly simple DTD are enough to describe every init task and background process to the OS, every preference in applications that use UserDefaults and CFPrefs (which is most), and I use them for storing structured data in and out of scripts that I throw together.

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.

giantrobot
0 replies
21h4m

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.

lmm
1 replies
18h46m

the language itself is very useful.

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

PaulHoule
0 replies
4h10m

People hate namespaces wherever they are used, but they are one of the keys to "programming in the large". The first year after Java came out the official docs for namespaces weren't complete and I had to go to a web page at NASA to understand exactly how they work, particularly in the strange case where you don't include a package statement -- people got used it though. (I'll make the case that Java was a software reuse revolution not because it was OO or had a particular implementation of OO but because of getting a bunch of "little" features right such as namespaces and memory management.)

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

SoftTalker
1 replies
1d1h

Yeah I always liked XML as a data format and combined with XSLT it is quite powerful.

PaulHoule
0 replies
1d

What I really like with XSLT is what you can do with user-defined functions. Not only are they helpful in implementing transforms but you can also write stateful functions that insert rows into a database or something.

_heimdall
3 replies
1d1h

Once you get that far, XSLT is waiting for you if you need to render XML to HTML.

andrewflnr
2 replies
23h48m

Yes, waiting in the dark, with teeth.

(I kid, mostly. It was a mild pain in the projects I used it for, and I've heard much worse horror stories than mine.)

_heimdall
0 replies
23h47m

Same. I've used it for small projects, like styling an RSS feed. I imagine it gets tricky fast in anything larger.

PaulHoule
0 replies
4h15m

My take is that XSLT comes from a different universe where Prolog became a mainstream programming language.

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.

tannhaeuser
0 replies
1d

Pro-tip: use SGML which has it all:

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

PaulHoule
3 replies
1d

My beef is that it doesn't have an RST writer. What I want is a central hub where I can suck in documentation that was originally in different formats and then manually edit it in a format where I can capture essential semantics and then feed it through the system again to produce output documents.

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

zdw
2 replies
1d

Ah, you want something like pandoc, but you can manipulate the internals as needed?

PaulHoule
1 replies
23h39m

Yes, and with a somewhat different focus. I wish I could throw in 1000 pages of reference documentation, align it semantically with a few pages of documentation about a particular topic and then enrich those pages with snippets pulled out of the reference material. And things like that.

Eisenstein
0 replies
15h53m

Sounds like an actually good use case for an LLM with RAG.

euroderf
1 replies
1d1h

rST and Asciidoc seem roughly equivalent in terms of capabilities. Are they roughly equivalent in terms of weaknesses and missing features, I wonder.

bobbylarrybobby
0 replies
23h29m

I think they're about equal, although asciidoctor has bold italics, which rST does not.

complex_pi
0 replies
23h52m

I can't test (no computer right now) but can't include directives achieve what you want?

__mharrison__
0 replies
17h49m

I am (was?) a committer to docutils (the main tooling for rST). One of the reasons I moved my tooling to md was because docutils was such a pain to work with (refusing to move to something like GitHub illustrates how hostile working with it is).

benji-york
10 replies
1d2h

I lament the lack of rST support in much of modern tooling.

I'm reminded of all of the alternate worlds that didn't quite come to fruition, but could have (Lisp, Smalltalk, BeOS, etc.).

Macha
6 replies
1d2h

This largely occurs because the only real spec of rST is the Python implementation. And tools written in other languages are loath to include a Python library just to support one document format. While writing a new compatible implementation is much more work given the larger scope than it is for Markdown.

So every language has a markdown implementation, but if you want to use rst in your Rust based static site generator or your PHP based CMS or whatever, it's a lot more work.

bluGill
5 replies
1d2h

Every language has its down markdown - but they are not compatible with each other unless you stick to the very basic which doesn't do much. Which is why every implementation has extensions - it isn't hard to add extensions and there are a lot of obviously missing things from the basic.

osmarks
1 replies
1d

CommonMark mostly fixes this.

xigoi
0 replies
22h20m

At the expense of being extremely complex.

Macha
1 replies
1d2h

Yet at the same time I'm able to write Markdown that parses and renders correctly in VS Code, Obsidian, and the Rust-based static site generator I use. Sure, Obsidian has incompatible features I could use like [[Wiki Links]] but I don't have to.

bluGill
0 replies
1d

That is easy enough as long as you are only writing a simple one page readme type document. To be fair that is the majority of what people write. However if you write anything more complex you will run into issues.

jcranmer
0 replies
1d1h

Is there any rich text format which is well-supported across multiple languages? The closest I can think of is HTML, but even that has its fair number of issues...

bunderbunder
1 replies
1d2h

An interesting commonality among the three examples you listed: they're all designed for a world when computing was a more solitary activity than it is now.

For Lisp and Smalltalk, image-based development is a genuine hurdle in the modern world. It complicates many aspects of modern highly-collaborative software development, including version control and continuous integration. I think that the language's respective hacker ethoses might also be a challenge in light of how often people switch jobs nowadays. I haven't used Smalltalk for pay money, but my experience has been that initially getting settled into a large pre-existing Lisp project does take more brain effort than it seems to with a language like Java. (In the long run I'd rather inherit a Lisp project, but I also acknowledge that first impressions are important.)

And BeOS was not a multiuser OS and didn't seem to have a clear path to becoming one. I'm pretty sure the main thing preventing it from becoming as much of a cybersecurity disaster as Windows 95 was is the simple fact that there wasn't any honey in that pot.

marcosdumay
0 replies
1d2h

Image-based development was never good. So we pushed it back again and again, so that we nowadays have a single image component we named "database" and most of the work is free from its problems.

That doesn't mean we stopped doing it.

marcosdumay
0 replies
1d2h

People don't add it because it is ugly and verbose.

And then people don't create any new format for its use case because it already exists.

Almost everything good we have only exists because some person irrationally decided to do it, against all common sense and logic.

necovek
9 replies
21h46m

It's funny how people are commenting as if reST was created as a competitor to MarkDown: it's actually quite the opposite. reST was a 2002 evolution on StructuredText from even earlier, and MD was first publicized in 2004.

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
I really, really don't see how the Markdown variant of the above is better in any way (note that I am not saying that reST is better either)? It's mostly the weirdness of history that has one prevail over the other, but both are good enough for their core goals.

johnmaguire
4 replies
21h43m

You've provided a very simple example that can be performed easily in both Markdown and reST.

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.

necovek
3 replies
21h29m

In general, either will be simple as long as your input is simple, and they will become complex as soon as you want something complex — I am pretty sure people here bringing the pitchforks are really not even aware of how reST looks like in the first place.

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

johnmaguire
2 replies
21h23m

I'm not arguing one is better, just that Markdown is simpler: it literally has less syntax. If I don't need all the bells and whistles of reST, Markdown is simpler to learn, use and likely implement.

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.

necovek
1 replies
21h10m

I am arguing that it's not simpler either. Check out the latest spec on Markdown: https://spec.commonmark.org/0.31.2/

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.

johnmaguire
0 replies
19h10m

Right, we can compare it to the reST spec: https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...

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!

lmm
3 replies
18h50m

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

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.

necovek
2 replies
12h27m

I guess you must really hate the double * for bold in either.

lmm
1 replies
12h1m

I do yes. I swear at some point there was markdown or some variant that allowed one single-character thing for italics and another for bold (maybe * for bold and / for italic? And _ for underline?). These days I've mostly just given up using bold.

necovek
0 replies
20m

You are right, there was a convention using that as well: I still have it in my muscle memory too (I always expect bold with a single asterisk). But I can't remember when and what that was.

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

IshKebab
9 replies
1d1h

I would strongly recommend using Asciidoc over Restructured Text. Even though Asciidoctor is written in Ruby which IMO is much worse than even Python, the actual RST codebase is a total incomprehensible mess. You can extend it with custom processing etc, but... fuck, I really want to never have to do that again.

Asciidoc just seems to be much higher quality in general.

jszymborski
5 replies
1d

I echo your sentiments, but sadly the Asciidoc python compiler (as far as I can tell) is deprecated and no longer supported. I think that leaves Asciidoctor as the only mature compiler.

There's a spec being drafted, so hopefully that will spur some more action.

For my purposes, Asciidoc is the best markup with the worst tooling, and Markdown is the worst markup with the best tooling.

FartinMowler
1 replies
23h49m

I run asciidoctor's Docker container. It does what I want it to do without leaving a mess behind on my laptop.

IshKebab
0 replies
21h34m

The trouble with that is it becomes a pain in CI. Nested Docker isn't fun.

YakBizzarro
0 replies
23h34m

Oh yes, I could mot agree more. We moved from Antora/asciidoc to mkdocs/markdown. Overall the situation improved (better HTML, faster builds, syntax highlighting of code,...) but I miss how good writing in asciidoc was

IshKebab
0 replies
23h38m

Yeah a nice Rust or Go-based implementation of Asciidoc would be fantastic. Having to deal with Ruby and Gems is not fun.

That's a mountain of work though and even if there is a spec, at this point it's complex enough and the Ruby implementation is enough of a de facto spec that I'm doubtful you'll ever make it past "this behaves differently to Asciidoctor" territory.

Btw a more recent alternative is https://github.com/jgm/djot which actually does have multiple implementations and looks like a way better option than Markdown, but maybe not as powerful as Asciidoctor still. I haven't tried it.

60secs
0 replies
1d

the toc macro on asciidoc is sublime

:table-caption!: :toc: macro :sectlinks:

toc::[]

__mharrison__
2 replies
17h45m

Except no one uses asciidoc either, and trying to manipulate it with Python is painful. Sadly (or not, depending on your opinion), the world has converged on md.

IshKebab
1 replies
11h51m

Markdown is definitely far more popular, but I see more book-length specification type documents written in Asciidoc. For example the RISC-V spec, or Ferrocene's Rust spec.

__mharrison__
0 replies
5h22m

I've written and published books (both physical and ebooks) with rST, asciidoc, and md. No format is perfect, but of those three md works best for me.

meribold
7 replies
1d

Wasn't reStructuredText the one where you can't make text a link if any of it is bold/italic/monospaced? IIRC, nesting of inline markup is generally not possible. It works in Markdown…

xigoi
3 replies
22h10m

IIRC, nesting of inline markup is generally not possible. It works in Markdown…

How do you write <i><b>x</b>y</i> in Markdown (without using HTML tags)?

xigoi
0 replies
18h39m

Oops, I forgot that underscores are a thing :D

meribold
0 replies
20h41m

Maybe Markdown doesn't allow arbitrary nesting of inline markup, but the combinations I actually wanted so far work. With reStructuredText, OTOH, I ran into limitations even though I didn't try to commit typographic atrocities.

remram
0 replies
23h4m

I had to scroll way too far to find this. All the arguments for RST are about how much more expressive the language is, how much care was taken in making it an abstract document tree. Yet there are simple trees you can't encode, even common ones that markdown handles fine.

I'm not using a language simply because it was aiming at something better, if it missed the mark.

ideasman42
0 replies
16h52m

Right, this is the one fairly clear down-side of RST, in practice I've found it's never been an issue - but it does seem like a strange constraint.

If you really want you can define bold italic text using some styling magic, but that's quite awkward.

hwayne
0 replies
23h54m

Yes, and this sucks.

keybored
5 replies
1d1h

A lot of lightweight markup languages get the basics right (except MediaWiki). Then eventually when it comes to making extensions—and especially if it is supposed to be terse, or look it—people get into the game of strategizing ascii symbol use (maybe `!` for images, maybe `@` for a figure).

At some point (and Rst[1] has a tendency to look like this, but only a little) it can start to look like some alternative, less regular markup language. Maybe you just use more backticks rather than angle “brackets”. Or maybe you have (like previously stated) marshalled all the ascii symbols so that all the common stuff can have a terse representation.

Maybe they should just make a regular-looking markup for the unusual cases/user defined things. They could do something like Pollen with its Latex[1] syntax inspiration.

[1] Initial caps for proper nouns

samatman
2 replies
1d1h

Words are styled the way they're styled. McDonald is a proper noun with two capital letters, Mcdonald is simply not correct.

I'll note that you didn't manage your footnote consistently, since you spelled MediaWiki correctly, rather than spelling it wrong as Mediawiki.

For some reason, you decided not to do that with rST and LaTeX, without explaining why. Latex and LaTeX aren't even pronounced the same way, so I fail to see the purpose in your (inconsistent) stylistic choices here.

keybored
1 replies
1d

I can make concessions for names that are based on real people.

I assure you my mistake was not because of good-intent towards Media[Ww]iki.

samatman
0 replies
1d

What I'm not understanding is why you've invented an incorrect rule for the English language and cited it. What purpose does this serve?

xigoi
1 replies
22h18m

Why is your username not capitalized, Keybored?

keybored
0 replies
21h53m

Poor self-esteem.

jawns
5 replies
1d2h

markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree

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.

strongpigeon
4 replies
1d1h

That’s pretty much how I feel. When the author writes:

This means you can extend Sphinx with new text objects! Say you that instead of an <image>, you want a <figure> with a <figcaption>. In basic markdown you have to manually insert the html

I can’t help but wonder what’s wrong with just writing HTML if you want those features? Why the extra layer?

scott_s
0 replies
1d1h

The author wrote an entire article explaining their use case which answers your question. Short version: they’re writing a book which they want to render to multiple formats with semantic linking between items and different rendering based on formats.

ryan-c
0 replies
1d

Convenience? I have a "spoiler" role for rST, for example, which works like this:

    # 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 = (
            '<input id="{id}" type="checkbox" class="spoiler" checked />'+\
            '<label for="{id}" class="spoiler">{text}</label>'
        ).format(text=text, id=_spoiler.id(src))
        return [nodes.raw('', html, format='html')], []
I don't want to do that manually, and this lets me write :spoiler:`Rosebud was the name of his sled`.

osmarks
0 replies
1d

Preserving the semantic content is helpful if you think you might want to switch the rendering later.

eddd-ddde
0 replies
1d

That's like saying why use C++ templates if you can just write the same function for every type that needs it. Now you don't need template instantiation!

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.

Karellen
5 replies
1d2h

Any sufficiently complicated lightweight markup format contains an ad-hoc, informally-specified, bug-ridden, and only slightly easier to use implementation of half of either DocBook or TeX.

nequo
3 replies
1d2h

Yes but Djot is pretty good though! Wouldn’t call it informal nor bug-ridden, it’s well thought out and doesn’t have many corner cases:

https://djot.net/

Designed by one of the authors of CommonMark, an attempt to specify a standardized flavor of Markdown.

keybored
1 replies
1d1h

Djot insists that this nesting of bullet points is wrong:

    - first
      - second
Instead you need this:

    - first
      
      - second
I’m very picky about the aesthetics of lightweight MLs so this is tough to swallow.

EDIT: By the way, recent comment from the primary developer: https://github.com/jgm/djot/discussions/310#discussioncommen...

kps
0 replies
1h26m

Not having used djot myself, does “rethink tight/loose lists” refer to that?

0cf8612b2e1e
0 replies
1d1h

I just wish it would move along already. I get it, some tough calls need to be made on edge cases that do not have a correct answer. Yet I want a 1.0 release so I can feel confident that the language will have staying power.

Then again, it is already in pandoc, so I suppose you can trivially move out of it.

the__alchemist
0 replies
1d1h

Indeed; Github will now render TeX in markdown documents, eg when displayed as a repo's readme. Very convenient.

mg
4 replies
1d2h

Markdown:

    ![alttext](example.jpg)
RST:

    .. image:: example.jpg
      :alt: alttext
The author prefers RST because:

    ... you can extend Sphinx with new text objects!
    Say you that instead of an <image>, you want
    a <figure> with a <figcaption> ...
What I would do:

        ![alttext](example.jpg)[caption]
And write a renderer which supports this syntax to create a figure with a figcaption. A markdown renderer is simple enough to write your own or extend an existing one.

eichin
1 replies
1d1h

Exactly - does anyone (well, maybe the author does since he did use markdown in previous works) use "basic" markdown anyway? There are always some extensions (either front-text metadata or syntax extensions like this one) in the "interesting" apps. (The python markdown module API kind of feels like it's entirely about extension and only a little bit about actually parsing, but that did make it easy to add an `ASIN()` token for a review site without needing a preprocessing stage...) That does make it a little worse for interchange, but that's maybe less important for markdown anyway.

eichin
0 replies
1d1h

(Even with pandoc, https://pandoc.org/MANUAL.html#extensions lists a bunch of syntax for things like this, brought in from github, php, and other places - for the example above, `implicit_figures` and `link_attributes` are a good starting point.)

romanovcode
0 replies
22h49m

Honestly I stopped reading article after this example. No, thank you. RST syntax looks confusing and overly explicit. I'd stick with MD thankyourverymuch.

Ericson2314
0 replies
1d1h

OK that specific example works, but what about his later problem vs solution one? One runs out of hacks pretty quickly.

pradn
3 replies
1d1h

I was thinking of how to setup a simple static blog without the baggage of a full-blow framework. Of course, I'd be re-inventing the wheel, but at least it'll make sense to me, personally.

What I came up with:

* Each page gets its own folder.

* An optional METADATA file in each folder has stuff like the type of the page (blog post, photo gallery, code listing).

* The index file can be in Markdown or rST or something. I'd just branch to a different parser based on the file name suffix.

This is simple and lets me evolve the blog over time.

For a personal blog, an ideal mix might be just branching to a different HTML converter based on the

vunderba
2 replies
1d

I have a customized version of pelican which is a python based static side generator. It basically supports this type of structure, except that in place of a physical separate meta-data file all the metadata goes in the front matter section at the top of the markdown file, and it gets stripped out of the actual rendered HTML.

pradn
1 replies
21h43m

That makes sense. The only reason to separate the metadata out is to avoid having to parse the main content files for front-matter. Plus the metadata files themselves could be in several formats, if necessary. I don't see a great need for that, however.

lmm
0 replies
18h33m

Hugo/Jekyll/etc. all work the way GP described too.

photonthug
3 replies
1d1h

I’ve done this thing a few times where I have a nice layout of about 5-10 pages of markdown docs, themselves rendered from more dynamic jinja templates, and feel that life is pretty good. Looks great, got a real build process for auto docs, but too big for a monolithic GitHub readme. Now the pain starts.

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.

paholg
2 replies
23h47m

Have you looked into mdBook? I haven't used it myself, but I've enjoyed the documentation of many projects that do and it seems really nice once you get past the point where a single readme file works well.

They also have some nice instructions on automated deployments.

https://github.com/rust-lang/mdBook

photonthug
1 replies
23h14m

Thanks, but this does not seem to involve hosting? What I'm saying is, static site generation is no problem at all, because even without all the choices for frameworks, pretty much everyone has to speak at least one templating language and read/write both markdown and rst anyway. But it's surprising that writing your project docs and rolling your own static-site generator is faster than figuring out github-pages and/or readthedocs hosting from scratch.

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.

paholg
0 replies
22h40m

That's what I meant by instructions on automated deployments. MdBook generates HTML, so you don't need anything fancy to host it.

This example shows a fairly short GitHub action to deploy to GitHub pages: https://github.com/rust-lang/mdBook/wiki/Automated-Deploymen...

fefe23
3 replies
23h58m

I don't understand the argument for rST. If you need more control than Markdown can deliver, then write your stuff in HTML to begin with.

I have written a ton of documents in plain HTML, including slide decks, documentation for customers, reports for customers, a blog. I have not written a book yet. If I were to write a book, I would use LaTeX because then the typographic fidelity of the output would be my paramount objective.

Plain HTML is actually pretty awesome. It allows you to encode the structure of the document and then style if however you wanted. When I started in this business, you had to use LaTeX for that kind of flexibility. HTML has gotten a bad rep, I think, because it's dark side of including Javascript and a ton of frameworks for whatever perceived goal looks easy and seductive and then forces you into serfdom by obstructing future reuse.

If you stick with the bare minimum HTML you'll be fine. Better than fine actually. Text processors can these days usually import bare metal HTML just fine if need be. They only fail if you give them the "processed food" output of some kind of rendering pipeline.

The only other system for documentation we haven't covered in this thread is troff for man pages :-) Any takers?

bluGill
2 replies
23h54m

HTML is a bad choice - I want to be able to reorganize my site without have a million dead links. Even if I know what the correct organization is today, requirements will change and so in the future something will be wrong.

With rST I can link to a section and move that section to a different document and the links all still work (or if they don't I get an error for each and so I know where to look). With markdown and html I link to a specific document and since each is a document generator there is no warning if I typo the page name (there are a number of tools to look for dead links in html). With markdown I cannot link into a section of the page, only the page itself (some extensions to markdown allow this)

paholg
1 replies
23h44m

What you see as annoying, I see as a strength. You shouldn't break links; they don't only exist in your site. People will have them bookmarked or shared on the web.

There's nothing worse than finding a post online that seems like it will cover your exact issue, but the link is now a 404.

bluGill
0 replies
5h41m

I get what you are saying, but the world is not static. The concept of bookmarks and deep links thus is flawed because they do not/cannot follow changes in the world. Bookmarks need to take a snapshot of the reachable web (this is probably impossible...) or they need to expire after a few months so that the world can change.

I would hate if all nurses manuals had to accept the bookmarks of some book from 1820 just because someone once had a bookmark to the bloodletting section.

betaby
3 replies
1d1h

asciidoc anyone?

schaefer
1 replies
1d1h

I keep my journal in a blend of asciidoc and markdown. In asciidoc, I love xref soooo much, which lets you make cross-document links to .adoc files that still work after being translated to html.

But I'm so sad that asciidoc isn't supported by pandoc.

argonaut68
0 replies
23h47m

+1. My current workaround is the use of asciidoctor to convert my docs to docbook. This format is supported by pandoc.

papascrubs
0 replies
18h33m

Right? So many features, and much easier to write than RST in my opinion. You can do things like dynamically reference other files to build tables:

  [%header,format=csv]
  |===
  include::tracks.csv[]
  |===
What about only including specific lines? Say from a log file or a separate piece of code? You can do that!

  [source,python]
  |===
  include::example.py[lines="1..10,15..20"]
  |===
Asciidoc solves nearly every problem I've ever run into with markdown and RST. I really wish it were more widely adopted.

asmeurer
3 replies
23h18m

The author claims that RST is nice because it's extensible, but as someone who's written some Sphinx extensions, I can tell you that extending RST is not as pleasant of a task as the author makes it out to be. I don't really know what it's like in Markdown world, but the underlying tools (Sphinx and docutils) are very difficult to work with, and make many implicit assumptions that make certain things difficult or impossible.

romanovcode
1 replies
22h48m

I think author should write HTML if they want extensibility so much. Not like RST is reading-friendly to begin with.

ideasman42
0 replies
16h54m

Keep in mind you might not _only_ be exporting HTML.

ideasman42
0 replies
16h55m

I've written a few Sphinx extensions ... it seemed OK to me, a bit awkward but long term - this is the kind of thing you do rarely & use often, so how nice it is to write extensions is barely an issue.

wodenokoto
2 replies
1d1h

I like writing markdown because it is so simple, but I agree with the author that it is too simple for more advanced stuff.

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.

smore
0 replies
1d1h

do we have a language server that can look up available references, headlines, figure names etc and help you auto complete?

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.

hwayne
0 replies
1d1h

Yeah, the rst lsp server (esbonio) can autocomplete and jumpto references in your project. I believe the markdown lsp can do this too, but only to a limited extent.

unoti
2 replies
23h31m

For the motivating use cases, I wonder if YAML and a simple script to transform to other formats as needed would be more effective, easier to read, easier to write, and easier to work with in general.

remram
0 replies
23h16m

What's the YAML syntax for "That's a _weird_ idea, [YAML](https://yaml.org/) is a data serialization language"?

AceJohnny2
0 replies
23h18m

No. <Michael Scott "nooo" meme>

While a tree datastructure like YAML (or JSON) can be mapped to a document (like HTML, or PDF), as demonstrated by the existence of the DOM tree and the (mis)popularity of XML, the one lesson we should have taken from XML is that it's awkward and you should not mix a tree datastructure with a text markup syntax.

Do not make humans have to construct their documentation as a tree first. Let them do in a free-flow way, with markup, and have tools internally convert it to a tree.

We've emerged from 20 years of XML-as-a-human-readable-datastructure dark ages. Let's not then make the opposite mistake.

thesnide
2 replies
1d1h

Rst is technically vastly superior to MD. Yet I predict that MD will prevail. VHS style.

I hugely prefer to write in RST, but as soon as I'm not alone we always switch to MD, given enough coworkers.

12_throw_away
1 replies
1d1h

Yep, it seems like the platonic ideal of a "worse is better" situation.

I do think this is, ironically, partly a documentation problem - when I last tried to create docs for a python codebase (several years ago), I found the rST docs to be sorely lacking in basic, introductory "here are the core mental models for how this works" sorts of content. Maybe the situation is better now? (Or maybe I just missed them, but not for lack of trying)

But I feel like then, it's obvious README.md prevailed and will continue to be the standard - you can use markdown for a very long time without ever reading any documentation at all. Worse is better, I guess.

bloopernova
0 replies
1d

In my opinion, I don't think it's "worse", just simpler. Plus it's more ubiquitous, supported by Github etc etc.

Although Github may not be the best yardstick there, because they render documents written in Emacs' org-mode too! (which I very much appreciate, I prefer writing in org to writing in Markdown)

I'm hoping that LLMs will make it more streamlined when documenting existing code. Not so much as a replacement for text written by experts, but in converting code into diagrams. LLMs or similar "understand" a codebase by tokenizing it (as is my understanding), so turning that into a nice documentation skeleton should be possible.

teamspirit
2 replies
1d2h

Isn’t this just a case of different tools for different jobs (or the right tool for the right job)? Rst clearly has some advantages for this use case but, at least for me, markdown is much faster and clearer to understand when jotting down my daily notes.

hwayne
0 replies
1d2h

Absolutely. I prefer rst for the use case of writing a technical book, because of the specific benefits I get from its additional complexity. My blog is still in markdown.

bluGill
0 replies
1d2h

Having done a little of both, I find RST is faster just because I can lookup whatever syntax I need to keep going while with markdown I often stop to scream because I can't make it do what I want. Either is easy enough to understand when reading raw text - this is mostly about good style though, RST gives you more options for bad style that is hard to read.

breck
2 replies
1d2h

Here is how you would do your image example in Scroll:

rst:

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

    image example.jpg
     caption alttext
"Directives" in rST are "Parsers" in Scroll. The item above would be parsed by the `imageParser`, which at ~50 lines of code (https://github.com/breck7/scroll/blob/b8fd72aa38742cc6cd575f...), is actually more code than the average parser.

To write your "exercise extension" in Scroll, you would just need to write a few lines of code definining an "exerciseParser". You could put that in the same file you use it in, or in a file named "exercise.parsers".

I think you should explore Scroll -- https://scroll.pub/ -- might do everything you need in a simpler way!

eviks
1 replies
14h51m

Out of curiosity, would you be able to write a parser that uses the markdown style for image links?

breck
0 replies
14h36m

Yes, you could do that. At some point soon (perhaps this already works today), you could probably just copy/paste the entire Scroll Parsers code (https://try.scroll.pub/scroll.parsers) into a ChatGpt or Claude.ai prompt and ask it to write one.

somat
1 replies
1d1h

"markdown is a lightweight representation of html"

No, markdown is a set of standards around transforming a good looking text file into a rich format(this is usually html, but it does not have to be). The most important part about markdown is that it is a "good looking text file". If a markdown extension does not result in good looking text it has failed the one point of markdown. This is why markdown editors leave me confused, the whole point of markdown is to write a nice looking plain text document, if you are going to use a specialized editor why not use a better format?

Note that markdown is a terrible document format, with only vague presentational cues and no semantic ones. it starts to suck real quick. However, it is a great idea if you want a good looking plaintext document. People understandably keep trying to "fix" markdown with better semantic options but these by and large miss the point of markdown leaving a ugly document.

So RST may be the best thing since sliced bread, but it is not really in the same category as markdown, the plaintext for one is decidedly ugly.

Ericson2314
0 replies
1d1h

Sure, the markdown AST is its own thing, but no doubt its a isomorphic to an obvious subset of HTML and that's not a coincidence.

Moreover, you are missing Hillel's second point, which is that there is nothing like an "abstract node" syntax which can be used for custom extensions. Lisp has (NAME ...) and XML has <NAME>...</NAME>, and these are separate from the choice of NAME.

(GitHub-flavored) Markdown's one extensible thing is

   ```NAME
   ```
but this isn't so useful because the inside is unstructured text (on purpose). You want a custom node which doesn't escape everything within, so you can have more regular or custom nodes on the inside.

smore
1 replies
1d1h

Markdown has a great linter in markdownlint. When I worked in rST, I found the syntax to be super extensible, and tables much easier to write (list tables! amazing!) but without an effective linter, writing in rST was consistently painful.

Whitespace has meaning, so I had to set up all sorts of indent highlights and dots for each space in my IDE to try to avoid screwing up the syntax inadvertently.

rst-lint and others exist, but don't seem to be maintained, and didn't seem to have documentation about how to add support for custom directives (which are definitely one of the key advantages of rST).

I'd write in rST again, but without an effective linter to stop me from making easy mistakes, I wouldn't be happy about it.

simonw
1 replies
1d2h

A few years ago I wrote up some notes on the subset of reStructuredText that's worth committing to memory: https://simonwillison.net/2018/Aug/25/restructuredtext/

I've started using MyST for my more recent projects, which gives me the features I care about from reStructuredText - references and table of contents - but lets me use markdown syntax, which is easier for contributors.

smore
0 replies
1d1h

Great points about links, especially external links — it makes a lot more sense in the context of a documentation site where you might have the same external link referenced multiple times in the site, but you only want to have to update it once if it changes.

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.

queuebert
1 replies
1d2h

Personally, besides it being a nice format, I use Markdown to honor Aaron Swartz.

Ericson2314
0 replies
1d1h

Haha on one hand its probably Aaron Swartz's worst work. On the other hand, this is definitely the best reason to use markdown.

RIP

kaizendad
1 replies
1d

While I definitely understand what the author is saying, the reality is that, for the majority of writing developers will be doing, having something that is easy-to-produce and easy-to-consume is paramount. There are tons of more powerful and flexible options than Markdown, but none that let you create a document that is both computer- and human-readable quite as quickly. Documentation that is written is better than documentation that isn't.

bluGill
0 replies
1d

Which is why I use rST - just as easy to write, but enough more powerful that I'm not left hanging when I realize I need to do something more complex.

Documentation that is written is better than documentation that isn't.

I have to disagree with this. I've read too many out of date documents. If documentation exists that isn't correct it is worse than no documentation at all. The only useful documentation is documentation that is correct, easy to navigate, easy to search, and easy to update as the world changes (there might be more?).

Good documentation is better than bad, it is debatable if bad documentation is better than no documentation or not (in part because some bad documentation is worse than others).

joekrill
1 replies
1d1h

The thing I like about markdown is that it's very readable as just a raw format. With the bonus that it's easily converted to HTML. But it doesn't need to be converted to HTML.

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

bluGill
0 replies
1d

I can look at a rST file and read it, and I think you will have no problem reading every rST file I've ever looked at. Sure it will take you a few seconds to realize you can ignore various syntax things, but that isn't a big deal and then the whole makes sense. Of course rST gives a lot more options to write documents that are not human readable, but it isn't that hard to make them readable.

daghamm
1 replies
11h48m

Can't we all agree that both suck and everyone should use org?

Jokes aside, org seems to have a more clear specification and is very easy so use. Why don't more people use it?

I think Github already renders README.org as good as README.md and READEM.rst.

ideasman42
0 replies
5h30m

ORG's tightly integrated into emacs & it's ecosystem. It's fine but I don't think there is an equivalent to Sphinx for large cross referenced documents, with different outputs formats & support for translations (different languages).

Perhaps some of these things exist - I may be wrong, if they do I doubt the system is as mature or well supported as Sphinx's.

concombres
1 replies
22h56m

I love rst. I love sphinx. I've written a lot of things with it.

But, I use markdown. Markdown is technically inferior, but it's just simpler and that's really what makes all the difference. There's things I can do in rst that are more logical, more powerful - and yet - I still use markdown and pictures.

To me, it's the usual problem that I like to illustrate with a config file:

while True:

  1. You need a config. You make a text file and write values in it. It grows. Its unmanageable. It's terrible.

  2. You write some proto to store the config. Its complex. It can do everything. It's relatively good but the more you use it, the more little problems show up. It looks like regedit, a sql database, a tree of trees, etc. 

  3. You throw it all away and write something with trade offs, that is reasonably simple, solve 80-90% of use cases and is otherwise somewhat limited. Sometimes, it feels like you might as well just use a text file.

ideasman42
0 replies
16h49m

Strange that everyone seems to think it's simpler, it seems might be a web-developer bias here.

I'm not a web developer and I don't find markdown especially easy/pretty/simple... I find it annoying when the same markdown can't be used in different places based on the rendering engine and there aren't standard ways to extend it.

Also, having trailing whitespace as part of the spec.. tsk!

bluGill
1 replies
1d2h

The problem with RST is the same with everything else: it isn't supported everywhere. I wrote a bunch of nice RST documentation at work, the next month some company wide team announced a new standard for documentation (backstage) which is markdown based, and has all the problems of markdown. (In their defense I'm not aware of any tool that would compete with backstage for what we need in a company wide documentation system)

f1shy
0 replies
1d1h

One solution:

https://pandoc.org/

Or “how I stopped caring about doc formats”

arp242
1 replies
23h40m

When I gush about rST to other programmers, this is the objection I hear the most: it's ugly. 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?

I like my Markdown documents to be nicely readable in source form. Because that's what I'm editing so being readable helps, and it's also what I read most of the time.

I don't think Markdown is perfect. I have gripes. But it's "good enough", and damn near everywhere already so it's "in the fingers", so to speak.

Markdown doesn't have a uniform extension syntax or native support for pre-render transforms.

Well no, but "Markdown" is also a standard with more implementations you can shake a stick at, whereas most of the alternates mentioned n the article are basically just a program written in $lang, and that's it. I think some do have a spec document, but also don't really have complete alternative implementations, so it doesn't really matter.

And I get the point; for my own website I have this ... piece of art ... to transform some of the HTML: https://github.com/arp242/arp242.net/blob/master/_plugins/ma...

On one hand: eww. On the other hand: it's not strictly needed, hard to do cross-platform, and has been working fine for a long time now. So whatever.

philistine
0 replies
23h35m

Well no, but "Markdown" is also a standard with more implementations you can shake a stick at

This ubiquity comes in large part from its lineage. Gruber based Markdown on the established cultural standards in raw text emails. The people who quickly adopted it where doing so based on familiarity.

RomanPushkin
1 replies
1d

No offense, but when I downloaded a sample PDF I expected to see a better formatting. The file is little bit clunky. I think it's not a failure of a formatter, but the design in general. The default markdown formatter in Leanpub works good enough, to a degree when I don't need to think about it.

So, while I understand all the good parts, I am still kinda not convinced it's a better option looking at the final product.

hwayne
0 replies
23h48m

No offense taken! Sphinx gives a lot of options for customizing pdf formatting, but I'm not thinking about that just yet. Step one is to get the book's content done, step two is to revise the content, step three is to revise it again... Getting it to look good is on my list, but ultimately a problem for future me.

zelphirkalt
0 replies
22h1m

rST is also much more powerful than Markdown. You can write an academic papar properly in rST. You can add custom directives implemented in Python and stuff. If I could make everyone use rST instead of Markdown, I would.

Of course Markdown is simpler in many aspects. But therefore it lacks many things that rST has.

xixixao
0 replies
1d1h

This is why MDX rocks. It doesn’t have all of this builtin, but you get a lot of the same benefits.

wiresurfer
0 replies
22h48m

I have grappled with the same conundrum. Here are my takes on documentation writing. First is the X axis of type of document we are called on to write. 1. There is personal writing. books included. 2. Personal Blogging and Dev Rel publishing. 3. Then there is developer tool documentation. [code snippets, sdks, libraries] 4. Then there is product documentation. [images, steps, how tos]

Then there is Y axis of tools. 1. markdown and with it Z axis of mkdocs, hugo, KMSs like obsidian <name everything markdown here> 2. rst 3. org? 3. wysiswg editors or anything custom.

I find - markdown both ubiquitous and somewhat approachable. for most beginners. with obsidian/logseq/... it can also work for non tech writers too. its also more widely supported. [Github i am looking at you] - dev rel/dev tools docs with sphinx and rst is absolutely godsend! also a vibrant ecosystem. - product docs with mkdocs x markdown if its a consumer facing docs with lots of images and need for customizing. rst if its a developer product.

---

I write my blog in markdown, https://blog.shaishav.kr

My team maintained https://userdocs.rapyuta.io in markdown for the last 4 years. https://github.com/rapyuta-robotics/rapyuta-io-docs

- we also maintained https://sdk.rapyuta.io/ & https://cli.rapyuta.io/ both in semiautomated rst + github actions setup

westurner
0 replies
23h44m

A Table of Contents instruction that works across all markdown implementations would be an accomplishment.

OTOH, Markdown does not require newlines between list elements; which is more compact but limits the HTML that can be produced from the syntax.

MyST Markdown adds Sphinx roles and directives to Markdown.

nbsphinx adds docutils (RST) support back to Jupyter Notebooks. (IPython notebook originally supported RST and Markdown.)

tristor
0 replies
1d1h

I use Markdown constantly, every single day, and I have tried multiple times to switch to RST and failed. Ultimately the reason Markdown works the best for me is that it gets out of my way. I can just type, I don't have to invest significant effort in formatting structures and can just write. This makes Markdown ideal for my primary use case, which is note-taking live during meetings, and because I already use it there, I also use it for writing blog posts, documentation, and most other document writing purposes. I will freely acknowledge RST is better for writing documentation and formal structured documentation, but the learning curve/barrier for RST is enough higher than Markdown, that it's not worth it for me to use both systems.

taeric
0 replies
1d

I dislike rST for how cumbersome it is with some of its markers. Trailing underscores, tons of dots, non-fenced sections, nested lists needing extra lines, etc.. It seems actively made to make it hard for me to read the source.

Now, granted, I am clearly ok with fenced sections. And I love org-mode for most all things.

smlavine
0 replies
1d2h

I think commenters are missing that the author is talking about this in the context of typesetting their own book. They aren't claiming that rST is better than Markdown in the general case; in general, Markdown's simplicity is a reason why it is so widely used. But that's not what the author is talking about.

skybrian
0 replies
1d

It seems like Markdown works pretty well for writing API docs, where the language has a tool for generating documentation that also gets things like type signatures from the source code itself.

The result of running that tool is always API documentation, so you might need something for docs that aren’t structured that way.

runningmike
0 replies
1d1h

Everything you can do with rst can be done now with markdown. But easier and better. The toolchain is superb now. MyST extends Markdown for technical, scientific communication and publication - https://mystmd.org/ and use Jupyterbook, which builds upon spinhx.

rk06
0 replies
14h16m

rST is very powerful but if you have rST-illterate people on your team and you would like them to contribute, tough luck.

Passion for most powerful tech can take you far, but not tohers in your team. For others, Markdown has a much lower barrier to entry and is easier to preview in your local editor

psychoslave
0 replies
1d2h

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.

Not really. Quoting https://en.wikipedia.org/wiki/Markdown

Its key design goal was readability, that the language be readable as-is, without looking like it has been marked up with tags or formatting instructions, unlike text formatted with 'heavier' markup languages, such as RTF, HTML, or even wikitext

So, for use cases that don’t make a good match of this chief constraint, Markdown might not be the most relevant option. It’s just as meaningful as saying that we prefer TeX over Markdown because fine typographical tuning is an important concern of our specific usecase.

I admit I already dealt with a screw using a hammer, not having the right toolset at hand. But when the situation don’t call for adhoc heterodox actions, I prefer to match a screwdriver with a screw and a hammer with a nail.

prpl
0 replies
1d1h

Sphinx + markdown (Myst) is a nice middle ground here I think, with the sphinx directives implemented as code blocks.

port19
0 replies
4h27m

So it's more complex than markdown while being less powerfull than latex or org-mode? What a waste

paxys
0 replies
1d1h

IMO the most important feature of markdown is that any random person, whether they are technical or not or know what markdown is or not, can view markdown-formatted text and understand it perfectly fine. A UI layer added on top is nice to have, but not at all necessary. Most alternative formats miss that critical point.

oglop
0 replies
19h39m

Ok well, that was insane.

I absolutely despise working with restructured text. Markdown I use allllll day long and it’s simple, fast, and a pleasure comparatively.

People like this just want to make the rest of us miserable.

numlock86
0 replies
1d2h

markdown is a lightweight representation of html

Never before on an article I've felt the vibes of the "I stopped reading there"-meme harder than here.

nailer
0 replies
1d

"Now here's how to make an image in rst:"

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

Great, I can close this article now.

mrled
0 replies
2h17m

I am kind of syntax agnostic and would be happy to use more complicated syntax in exchange for more power. (I have a lot of HTML inside my Markdown files, too.) However, my use of rST has been in Sphinx, and I want to love it because it's quite powerful, but it's so slow. Am I missing some configuration or third party package to fix this? I wrote about 15k words of English text in rST in Sphinx to document a project[^1], and Sphinx's build speed was many times more an impediment than my unfamiliarity with rST.

[1]: https://pages.micahrl.com/progfiguration/

morbicer
0 replies
1d2h

RST might be technologically superior but markdown is easy to write and has a huge ecosystem.

For hobby usage, use whatever. But I would strongly oppose anyone who would try to make RST standard at my workplace.

A scrum-master, PO or marketing can write markdown. RST would be a hard sell.

mmphosis
0 replies
23h55m

I prefer What You See Is What You Get (WYSIWYG.)

mjburgess
0 replies
1d1h

I believe the big selling point is supposed to be the directives syntax of rST. I had a similar need to extend markdown, but pandoc already supports directive syntax -- and so do some libraries, eg., the marked library, which I use to render MD as HTML in-browser rather than with pandoc.

The iirc, syntax is :inline{property} and

    ::: block-directive {options}
        contents
    :::
It doesnt nest well, so I applied any document-level styles using the filename; but I'd imagine the yaml-style lead-in tags should be the correct way to do it.

louwrentius
0 replies
1d2h

The one-line summary is:

I think Restructured Text is better for writing books than Markdown.

That would be a better title.

ktosobcy
0 replies
22h51m

If it's a matter of preference then whatever.

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…

kelsey98765431
0 replies
1d1h

When you call a book v0.2 and say "now with epub, get it here" in the first line of your blog on why not to use the most popular of a thing, I am assuming we are going to be having a above board conversation about pros and cons, and I an receptive to your position.

When the first link is also the second link, and both are to BUY a 15 dollar book with the default "pay anything price" bar set to 20, I am just clicking out and ignoring literally everything in your marketing post.

Others can discuss this RST thing I have never heard about, I am just here to point out you have now alienated one of your potential converts. Put the book link at the bottom, and dont double link to the same purchase page in the same paragraph. FFS.

karaterobot
0 replies
1d1h

I thank the author for explaining their reasoning. I still disagree, but I appreciated reading the argument.

Apart from the ugliness of the syntax from a devex perspective, I think one of the big advantages of Markdown is that it's highly readable even without being interpreted, which rST is not. So if you have a markdown document and no markdown interpreter, an average person can still make more or less perfect sense of the contents, including the hierarchy and emphasis.

jasonpeacock
0 replies
1d2h

Lemons vs limes. They're both markup languages, but they have different purposes.

Yeah, using markdown to write a book is very limiting and doesn't offer the control needed for typesetting.

OTOH, using markdown to write is liberating - you only get a few markup options, so you can focus on the content:

    [It is] notable that the Feynman lectures (3 volumes) write about all of
    physics in 1800 pages, using only 2 levels of hierarchical headings: 
    chapters and A-level heads in the text. It also uses the methodology of 
    sentences which then cumulate sequentially into paragraphs, rather than the
    grunts of bullet points. Undergraduate Caltech physics is very complicated 
    material, but it didn’t require an elaborate hierarchy to organize.
    
    Edward Tufte, forum post, ‘Book design: advice and examples’ thread

insane_dreamer
0 replies
1d1h

I would say which is better depends on the use case. For note taking and most simple documents, Markdown wins hands down due to its readability and speed. For complex document sets where custom rendering may be required, rST+Sphinx is probably what you want.

innocentoldguy
0 replies
23h5m

I don't mean to hijack a conversation about ReStructuredText, but if you're looking for a markup language that gives you more than Markdown, look at AsciiDoc rather than ReStructuredText. I have written technical documentation using all three for years and AsciiDoc is superior to both ReStructuredText and Markdown, in my opinion.

For example, Markdown's and ReStructuredText's support for tables is cumbersome to say the least. AsciiDoc's table formatting is much easier to read, write, and maintain, and AsciiDoc tables are more robust, supporting headers, captions, custom dimensions for tables/rows, and complex formatting within tables.

Some other benefits include:

• A single, standardized format where Markdown and ReStructuredText do not (in other words, there are no "flavors" like you have in Markdown).

• Concise and readable syntax.

• A more gradual learning curve that ReStructuredText (probably due to its consistency and excellent documentation).

• Superior styling options for your output.

• A superior toolchain to the other two markup languages.

• A rich set of built-in documentation features, so you rarely have to rely on third-party plugins.

AsciiDoc was designed from the ground up for technical documentation, whereas the other two get shoehorned into that role.

Having worked extensively with all three, I can't recommend AsciiDoc highly enough.

hintymad
0 replies
23h29m

.. image:: defines the image "directive". When Sphinx reads it, it looks up the registered handler for the directive

And the author continues to explain how rST is convenient and flexible to a doc engine like Sphinx. This kind of argument confuses me as a user. That is, why would I care? I just want to write my doc fast with minimal effort, and couldn't give zero attention to how Sphinx works. Wouldn't an average user like me should just ask: what will rST offer that is 10X better than Markdown?

gregopet
0 replies
23h59m

I used to hate Markdown (am partial to AsciiDoc myself) but it has "won" and I've just accepted it & use it every day. Not the first time an inferior product did so, and won't be the last. There are a few hills I'd die on, but Markdown alternatives are not one of them.

gigatexal
0 replies
1h48m

I’m not convinced. Markdown is cleaner imo and basically the standard. I see no reason to move.

geenat
0 replies
1d

IMHO, ignoring the parsing difficulty, the main issue with Markdown is it's difficult to write for non-technical users- 1 misplaced character can mess you up if you stick to the "spec".

Markdown has already won over the technical users.

Enjoy your infinite support tickets caused by markdown. RST does nothing to help this.

fridder
0 replies
21h35m

Perhaps it is just how it was implemented the last time I used it but rST+Sphinx was so finicky and annoying that engineers just stopped updating the docs.

fireflash38
0 replies
21h43m

I used rST and Sphinx along with a custom built test reporter to generate a huge amount of test documentation for compliance. It really was nice to work with, especially since it is the default for python docstrings too.

fermigier
0 replies
3h5m

Typst has a cool syntax and is highly extensible.

I wish there was a way to use it to render HTML and not just PDF.

dheera
0 replies
18h6m

I prefer just vanilla HTML. It's easy to read and you can tack a stylesheet at the top to make it look actually nice and directly renderable in a browser without needing any parser.

crowcroft
0 replies
23h24m

Markdown might not be the best at anything, but it's pretty good for a lot of use cases and is beautifully simple. I can teach a non-technical friend markdown in about five minutes.

bradboimler
0 replies
1d

Sure, for quick throwaway notes or messaging apps Markdown is fine. But if I'm gonna sit down and write a proper document? I prefer handcrafting HTML.

blt
0 replies
1d1h

If the author is here: Before the first code display, where you write:

    > Here's how to make an image in html:
I think you meant "markdown" instead of "html".

beej71
0 replies
23h47m

I started looking at converting my books to use Sphinx (from pandoc) and got almost there. What stopped me was something a little odd: I wanted to use different fonts in a link, notably some proportional and some monospace in the same link. And it was my read that this wasn't possible...?

andrewflnr
0 replies
23h39m

...Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason.

I guess this is why he's not using Pollen, which is explicitly designed for this sort of thing, but based on Racket.

I actually settled on rST for writing fiction manuscripts, I think because I actually liked the syntax? Maybe I just needed proper header support. I'm compiling to DOCX via pandoc, so I'm not using the extensibility in the slightest. Anyway, it's amusingly validating to see someone else use it for a similar job.

__mharrison__
0 replies
18h4m

I wrote my books for years with rST. (I also used Asciidoc, and one publisher wanted me to use Word.) Recently, I migrated all of my tooling to Markdown.

It turned out that no single markup language supported all of the features required to make physical books, so I would need custom tooling regardless. The rest of the world was moving onto MD, and even though I'm a huge Python fan, rST is painful, and writing tooling with it is even worse. (I also have commit rights for docutils.)

I don't regret my choice one bit. It has made my life much easier, and I can work much faster today.

Morizero
0 replies
1d1h

You just need a regex to transform it into <img alt="alttext" src="example.jpg"/>.

Is this what the author means by markdown being lightweight, since the inverse isn't true except trivially?

KronisLV
0 replies
1d

I like Markdown because it's simple and doesn't give me that many headaches.

You know what I don't like? HTML, for user submitted content in particular. The mess I've seen, after someone opted for using HTML for messages in a system, because that's what JS based editors were available for at the time. Endless need to work against XSS, with more and more incremental updates needed to the sanitization logic, some of which broke the presentation of the data in the DB.

Never again. Markdown, BBCode, anything but that.

As for docs? Currently just some Markdown, because that's what GitHub, GitLab, Gitea and others all know how to render.

Maybe something like https://www.mkdocs.org/ for the more standalone use cases.

JoshTriplett
0 replies
1d

I do appreciate that reStructuredText is extensible and Markdown (currently) isn't. I don't think that's an argument that outweighs rST's verbosity. But I do think it's an excellent argument for adding a standard extension point to Markdown.

Ericson2314
0 replies
1d1h

I am proud to say this is might be the first time I finally agree with Hillel Wayne and something (at least mildly) controversial.

Decabytes
0 replies
1d

Another good documentation choices is Racket’s scribble^1. I like that you can embed Racket code directly into the text, and the language oriented programming of Racket means the syntax is more ergonomic than other systems. There is also pollen^2 but that is more set up for online books by default

1. https://docs.racket-lang.org/scribble/

2. https://docs.racket-lang.org/pollen/

Animats
0 replies
1d1h

If you want all that extensibility, use TeX or something similar. Or write HTML yourself. Markdown was supposed to be simple. Yes, you can't do everything you can do in HTML. That's the point.

AndIHateLatex
0 replies
16h55m

I never gave rST an in-depth look. This article made me.

I am utterly disappointed.

I want markdown for writing loose text in a way that will be shared with and edited by non-technical people. If something is not formatted such that it can be placed in-line, then we're entering the real of "function" abstractions, which non-technical people DESPISE WITH A PASSION. They won't say it, but I'm old, and wise enough to know it's a mistake.

In other words, Markdown is just an expanded BB Code for me. And it does its job very well, because BB Code was insufficient.

So that's the context in which I'm disappointed with rST here. Because it look like... A poor man's LaTeX. This stuff is way too complicated for Markdown's use case, and way less complex than the demands of a book. I don't want to take the use case of LaTeX and use a worse tool. Disappointment. That's all.

Analemma_
0 replies
1d1h

To me rST targets such a narrow middle band of scenarios that I can't see any compelling reason to use it. For simple documents where Markdown is enough, I'll use that, and if I need more layout configuration and control I'll use LaTeX or HTML. What is rST for?

8organicbits
0 replies
1d

it's that simple markdown is exceptionally bad. It doesn't have a uniform extension syntax or native support for pre-render transforms.

I feel like "simple markdown" is a straw man here. If you're doing anything complex with markdown you're going to pick a flavor and learn it. Many flavors of markdown can do the things described.

Here's a Hugo figure which looks easier to understand than the "ugly rST" equivalent: https://gohugo.io/content-management/shortcodes/#embedded-sh...