>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 135 days ago [-]
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 135 days ago [-]
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).
cqqxo4zV46cp 135 days ago [-]
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 135 days ago [-]
But nobody (relatively speaking) uses CommonMark, and everyone uses Markdown
input_sh 134 days ago [-]
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.
deathanatos 135 days ago [-]
> 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.)
fragmede 135 days ago [-]
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.
account42 134 days ago [-]
That sounds horrible. You should never mess with the semantics of standard shortcuts like that. Please let paste mean paste and not "smart" paste.
sethaurus 133 days ago [-]
This is very common feature of rich-text (and markdown) editors. GitHub comment boxes do the same thing even though they are not WYSIWYG. Confluence and Notion do too.
literallyroy 133 days ago [-]
Interestingly it annoys me when other tooling *doesn’t* do this
m-p-3 135 days ago [-]
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.
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.
deathanatos 135 days ago [-]
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.
account42 134 days ago [-]
And even HTML was not safe because <b> and <i> were too easy so now we have <strong> and <em> because somehow those are more meaningful.
collinmanderson 132 days ago [-]
The worst part of the <i> to <em> migration is now <em> often gets used for book titles, which is completely wrong. Book titles aren’t emphasized, they’re italicized.
If someone hits control+I, or an italics button, it should use <i> tags, not <em>.
pitaj 134 days ago [-]
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 134 days ago [-]
I agree with you on that.
What about * for bold, / for italic and _ for underline?
ysavir 134 days ago [-]
/ is too commonly used, such as when making a list of replacements/alternatives/synonyms. It works fine when it's just the text as written, but if it was parsing and turned that list to replacementsalternativessynonyms, it would only be getting in the way.
bmacho 127 days ago [-]
You shouldn't parse '/' in foo/bar/baz or in foo / bar / baz.
If people want to make foo or foo bar italic, they write /foo/ and /foo bar/.
adrian_b 134 days ago [-]
True.
Perhaps //italic text// would be acceptable.
account42 134 days ago [-]
// is common in URIs.
bmacho 127 days ago [-]
HN uses *italics*.
I, myself, prefer /italics/, _underline_ and _bold_ in text, if there is no formatting. I feel that these 2 are the least arbitrary, they almost work without agreeing on their meaning beforehand.
jgruber 127 days ago [-]
I have no regrets on this one. I thought people would use both, and people do use both.
keybored 134 days ago [-]
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 134 days ago [-]
>having it in the raw form while typing
This is actually an option in the settings (on desktop, at least).
keybored 134 days ago [-]
Aw that’s embarrassing. Thanks.
strken 135 days ago [-]
> 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 134 days ago [-]
> 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 135 days ago [-]
Markdown is the Unix of rich text formats.
gm3dmo 134 days ago [-]
Ready for Markdown wars?
bitwize 131 days ago [-]
You mean like original recipe vs. GitHub flavor vs. Reddit flavor vs. CommonMark? We're already there, dude.
billti 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
Agreed. Mandate function docstrings? You'll get "Function FlargleBlab blabs the flargle" docstrings. Just useless.
runlevel1 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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).
unethical_ban 135 days ago [-]
Yes!
Markdown is great because it is a way to write and store documentation in plaintext, in a way non-documentarians can follow.
duskwuff 135 days ago [-]
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 135 days ago [-]
Yes, though I would expect most news-folks to use some form of WYSIWYG for writing?
jgruber 127 days ago [-]
> In fact, 90% of what I wrote before I knew markdown was valid and decently formatted markdown already.
Bingo!
tjoff 135 days ago [-]
>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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
There's no reason for this to be all or nothing. This seems perfectly readable to me:
Even if you've never seen markdown before, it's pretty obvious.
tjoff 135 days ago [-]
How often do you refer to the logo? Try something like this:
You know what it is, but you have no idea what it looks like. Maybe it is a garbage picture that doesn't really add anything. Or maybe the picture is a necessity to understand the architecture of the system. Someone put the time and effort to create that picture, you'd imagine for a reason. Maybe worth having a look?
Maybe, just maybe, looking at that image is a good idea to do before reading 20 pages of documentation? Probably a good idea to look at even if you only intended to glance at the documentation for 20s.
Because that's what markdown mostly is in my experience, documentation. And the images, if they exist, often are a very important part of that.
Now some images are garbage, but you don't know because the alt-text will not be "Superfluous image that doesn't add to the understanding". Maybe it depends on the reader, is the reader fluent in design patterns (and crucially, is the project following the design pattern as is or have they made their custom modifications to it?).
But in reality it will likely be a flowchart. Kind if an important piece that really help when reading the text. Or maybe just an image of a header and all the field sizes. Can you do it without it? Sure. But remember that not all documentation is perfect, it might not have had someone pouring his/her heart in it. It might have been rushed. So as often is the case you actually do need both the image and the text, not just to help understanding (which alone really is reason to make sure you look at both) - but because you need both to get all the information.
I sigh when I see a .md. Especially in documentation, because in reality that probably means that I have to either get the dependencies and look up the build process to build it myself. Or I have to go to the official project web page and browse the documentation there.
If it is a .txt or .pdf I know what I'm in for, and I know I have the tools needed to view it.
8organicbits 134 days ago [-]
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.
tjoff 134 days ago [-]
Markdown can't display images at all, either... Which is my point.
(you know you can write paths in a .txt file too?)
bulletninja 134 days ago [-]
But you would have to invent or assume a format for that .txt, and markdown is easily rendered if needed
tjoff 134 days ago [-]
Invent a format? How about, "The system overview has been illustrated in images/system-overview.png"
We use markdown because it is plaintext and accessible. Oh, but you have to convert it yourself. How? Well every project is different but I'm sure you can find a Makefile somewhere in the project. Good luck!
Again, the point again is that markdown is not readable alone.
If it is, then a .txt is strictly superior. If it is not, then never, ever, present it as the final product. Always ship the generated artifacts. The only point you want to actually see the .md file is if you want to make changes to it. Is making changes the primary usecase for your markdown files? I'm going to assume, no.
AndIHateLatex 135 days ago [-]
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).
packetlost 135 days ago [-]
> 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 135 days ago [-]
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.
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 135 days ago [-]
Ah, good to know! Is that tooling public anywhere, or was it pretty tailor-made just for the Rust book?
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 134 days ago [-]
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!
paholg 135 days ago [-]
Awesome! You and Carol rock!
steveklabnik 135 days ago [-]
Thanks! She gets 100% of the credit in this case though :)
> 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)
All my documentation at work is written in a dialect of markdown. It's absolutely the thing you want, together with a good parser and content management system for producing a site with search, navigation etc.
hinkley 135 days ago [-]
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.
jgruber 127 days ago [-]
Well said. But, uh, there’s no “maybe” about Markdown being intended for writing a blog. That’s literally exactly what I made it for — for me to write Daring Fireball.
rcarmo 135 days ago [-]
Yeah, I still have thousands of Textile pages, but all of my newer stuff is in Markdown…
thomascgalvin 135 days ago [-]
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.
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.
about keenwrite, touting "producing beautifully typeset PDF files" and not giving a single PDF example, ideally its documentation, is a missed opportunity, to say the least ;-)
bluGill 135 days ago [-]
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.
zelphirkalt 135 days ago [-]
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.
pclmulqdq 135 days ago [-]
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.
nrr 135 days ago [-]
"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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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.
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.
reknih 135 days ago [-]
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.
134 days ago [-]
josephg 134 days ago [-]
Thankyou for your work! It’s a delight.
enema_bag_jones 135 days ago [-]
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 135 days ago [-]
HTML output with Typst isn't possible yet, but it has a high priority.
g8oz 135 days ago [-]
Indeed, I don't see the reason for someone to learn LaTex now that Typst is here.
conaclos 133 days ago [-]
In computer science, we still need LaTeX because conferences and journals require the use of their official LaTeX template.
auggierose 134 days ago [-]
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.
red_admiral 134 days ago [-]
TikZ/PGF ?
g8oz 134 days ago [-]
The Cetz package looks like a promising alternative to TikZ.
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.
red_admiral 134 days ago [-]
My problem with the TeX ecosystem is it's so non-modular. Bring in this package to add a new font with some extra dingbats, and suddenly you lose proper linebreaking inside boxed environments. And so on.
__mharrison__ 135 days ago [-]
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 134 days ago [-]
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}.
BeFlatXIII 133 days ago [-]
Regarding point 2, would that mean you’d suggest using a newline instead of a space to separate sentences?
__mharrison__ 134 days ago [-]
Awesome. Can you point to a repository with an example?
Also, is there a book that you would recommend for learning LaTeX?
pclmulqdq 134 days ago [-]
Overleaf has several examples that are not bad. I am currently working on a book and the Krantz template is a pretty decent example of how you might structure things (although the package itself is total spaghetti). The ACM and IEEE paper examples are also both OK, but are short so they cut some corners.
I'm not sure if there is a good book on LaTeX, ironically.
__mharrison__ 134 days ago [-]
I've always used memoir.
pclmulqdq 134 days ago [-]
The publisher wanted krantz. It's very pretty, but I wouldn't self-publish with it.
bitwize 135 days ago [-]
TeX is old and busted; Typst is the new hotness. Written in Rust, too!
pclmulqdq 134 days ago [-]
"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 134 days ago [-]
What? Typst is open source and has a CLI, it's not just an online app.
JW_00000 134 days ago [-]
I think the previous author is confused because if you google "Typst", you end up at https://typst.app, which seems to only advertise the web GUI and not the open-source CLI tool.
qwerty456127 135 days ago [-]
> 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 135 days ago [-]
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
josephg 135 days ago [-]
Easy is relative. Latex is sooo much uglier than typst:
#let important(body) = {
text(red, body)
}
But whatever you do, #important[Dont *panic*!]
"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.
eviks 135 days ago [-]
> 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
michaelcampbell 133 days ago [-]
> asterisks/underlines for italics already require familiarity unlike the much more intuitive /italic slashes/
This has always baffled me. _underline_, /italics/, bold.
yencabulator 132 days ago [-]
And then you have programmers talking about _private_method and /some/path/
michaelcampbell 127 days ago [-]
Then put code things in `grave_marks`, etc.
eviks 131 days ago [-]
not a good argument given the fact that underscore _is_ already a bold markdown syntax
yencabulator 131 days ago [-]
Yeah but CommonMark was carefully specced to make sure _foo_bar doesn't trigger that, and _foo_ is not a common style of identifiers -- where as /etc/ is a common convention, when you specifically want to refer to contents of a directory.
eviks 131 days ago [-]
If it's so carefully specced (though how do you italicize a part of a word than? Seems to me more commonly important vs some niche identifiers), why did you bring _ up as an issue?
But also asterisk is a common form for multiplication just like / is for division/separation (which is more common than paths)
So you already have this design issue, but on the other hand at least you could have the benefit of visually intuitive markup, which isn't the case with markdown
Multiple multiplication signs can be used with spaces, x * y * z.
Markdown makes no mention of italics. It speaks of emphasis and strong emphasis. Underscore and asterisk are interchangeable, doubling gets the strong variant. Using slashes for italics doesn't fit into that scheme.
eviks 131 days ago [-]
Oh, so you meant that if _ were underlines, then you couldn't have this special case because you wouldn't have two symbols to play with and have different behavior for?
Yeah, I'm fine with that, it's a bad original design decision to waste two symbols for the same thing in the first place, and the subtle _foo_bar vs foobar differences go against the simple nature of the markup
All these _foo_bar intricacies should be dealt with via escaping (or an even better alternative design of using some other marker types like _[] to allow free use of the marks)
> Using slashes for italics doesn't fit into that scheme
Sure, because that's a bad scheme, and not mentioning such a common thing as italics doesn't help either since the whole point is visual intuitiveness, so markdown still fails here (and adds a needless cost of 2 extra symbols "for the strength")
> Underscore and asterisk are interchangeable, doubling gets the strong variant.
But you've just shown that they aren't
yencabulator 131 days ago [-]
> should be dealt with via escaping
That's programmer-think, while markdown was meant to cope with existing conventions as much as possible. Markdown was primarily a pragmatic thing that worked with people writing without needing to think of many rules, and that's exactly why it got so popular.
Wanting /italics/ is just your opinion, not some objective ideal.
eviks 131 days ago [-]
You whole conter-argument is "programmer-think", none of this _foo_bar or even paths is that relevant in the broadest use cases of the markup
> Markdown was primarily a pragmatic thing that worked with people writing without needing to think of many rules, and that's exactly why it got so popular.
That's wishful thinking, the whitespacing, especially in such common thing as lists, is something that requires thinking. And with urls it's a common fail to forget which () [] go where.
And there is nothing pragmatic/conventions about this strong/emphasis nonsense, that's just following HTML <em> spec, none of common email/blog post plain text writers think in HTML standard, they think in terms of bold/italic/underline
> Wanting /italics/ is just your opinion, not some objective ideal.
Wanting is not an opinion, it's a desire. Also /italics/ is objectively more intuitive
> 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.
ori_b 135 days ago [-]
Yes, that is a good rephrasing of the rest of the paragraph you quoted.
qwerty456127 135 days ago [-]
> 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 135 days ago [-]
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.
red_admiral 134 days ago [-]
When you're putting documentation in the same commit as the relevant code - which is good practice, at least around here - then it's often useful to be able to read not just markdown but a diff of markdown as plain text in ${editor}.
BeFlatXIII 133 days ago [-]
> 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.
Revive Textile? It was one of the inspirations for MD, IIRC.
philistine 135 days ago [-]
> 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.
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.
ska 134 days ago [-]
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.
BeFlatXIII 133 days ago [-]
What are some non-emacs tools (more advanced than notepad.exe or TextEdit.app) for editing org-mode?
kevin_thibedeau 135 days ago [-]
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.
red_admiral 134 days ago [-]
Markdown has 30 flavors because it has over 30 different ecosystems using it. We have github flavored markdown, gitlab flavored markdown, MDN markdown etc. because github, gitlab and MDN are all using it. If you forced everyone to move to rst, then you'd see flavors cropping up soon too.
Even if rst has a generic extension mechanism, on github you'll spend a lot of time referencing commits, tags, users, pull requests and that kind of thing. So you end up having to know a domain-specific language anyway, whether it's formally presented as an extension mechanism to the language or as a dialect.
humanfromearth9 134 days ago [-]
> I don't want to write a book. If I did I'd use LaTeX before RST.
You'd want to use Typst, not LaTeX. I'm rewriting my CV with it, it's fantastic. I can now finally put the CV contents in a JSON, and generate the PDF programmatically, with lots of computed values by my own algorithms, the layout is simple, nothing stands in the way, nothing feels out of its place. And compilation is so fast... Really, forget LaTeX, embrace the 2020s.
makeitshine 135 days ago [-]
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.
necovek 135 days ago [-]
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 135 days ago [-]
> 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.
jgruber 127 days ago [-]
If rST were actually easy to write and read I would have just used rST instead of creating Markdown.
__mharrison__ 135 days ago [-]
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.)
jgruber 127 days ago [-]
I couldn’t say it better myself. Thanks.
edgarvaldes 135 days ago [-]
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 135 days ago [-]
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
andrepd 135 days ago [-]
This is pretty much the paragraph that follows the paragraph you cited...
michaelcampbell 133 days ago [-]
If you'd read past that, the author says "yes, those are good reasons, I would too".
__mharrison__ 135 days ago [-]
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.
kaycebasques 135 days ago [-]
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.
pbowyer 135 days ago [-]
> 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.
ak217 135 days ago [-]
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 135 days ago [-]
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...)
eska 135 days ago [-]
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.
thechao 132 days ago [-]
I did not know about Sphinx until your comment (I'll get to my 2-day delay in response, briefly). I've been doing technical writing "on the side" as my dev work allows, for 20+ years. I've been a TeX/custom-XSL sort of dude the whole time.
I just ported a 200+ page book documenting an internal language/VM/abstraction-layer to Sphinx ... holy moly, this is a life changing system!
I wish the documentation for Sphinx, itself, had a lower ramp and/or more examples; otherwise, I'm still in a pretty fantastic honeymoon phase.
My two main lines of research are how to build good looking PDF (books); and, some sort of system to let me cut a book into POSIX compliant man pages by chapter/section.
dlivingston 135 days ago [-]
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.
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.
kaycebasques 135 days ago [-]
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.
0xedd 135 days ago [-]
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 135 days ago [-]
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.
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 135 days ago [-]
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.
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.
mixmastamyk 135 days ago [-]
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.
__mharrison__ 135 days ago [-]
Until you need to make a physical book with Sphinx or write custom tooling with it...
shepherdjerred 135 days ago [-]
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.
bluGill 135 days ago [-]
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.
irskep 135 days ago [-]
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).
throw310822 135 days ago [-]
Ok, what about DITA?
kaycebasques 135 days ago [-]
Also very powerful. Haven't worked with it in years; need to revisit.
einpoklum 135 days ago [-]
> 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.
kaycebasques 135 days ago [-]
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.
I'm not really sure what your point is. What you're saying agrees with both the parent and the OP.
einpoklum 135 days ago [-]
My point is that the reason GP prefers rST is a reason not to prefer it, usually.
BerislavLopac 135 days ago [-]
> 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.
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 135 days ago [-]
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.
rpdillon 135 days ago [-]
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].
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).
lmm 135 days ago [-]
> 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.
jgruber 127 days ago [-]
The comparison JSON is apt.
The first few years after I released Markdown, it was far less popular than I expected and hoped it would be. But it grew, and then for a years it was as popular as I’d expected. But then it kept growing, and now it’s far more popular and widely used than I’d ever thought possible. I genuinely now think it’s used in many cases where it shouldn’t be, and exposed to non-technical users who should be using something WYSIWYG, not markup.
simonw 135 days ago [-]
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.
SoftTalker 135 days ago [-]
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 135 days ago [-]
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).
Spivak 135 days ago [-]
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.
paiute 135 days ago [-]
The article convinced me that markdown is better for its purpose.
latexr 135 days ago [-]
> 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 135 days ago [-]
Usually, the colloquial conflation of Markdown with CommonMark and the numerous Markdown-esque dialects is helpful language, I've defended it here before.
> 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 135 days ago [-]
> 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.
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 135 days ago [-]
> 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 135 days ago [-]
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 135 days ago [-]
Yes, that’s why I said “some”. I don’t understand what’s ambiguous about that.
The_Colonel 135 days ago [-]
The question is whether these are even Markdown implementations, or rather something like "Markdown-like format".
js2 135 days ago [-]
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.
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.
chrismorgan 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
> 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.
keybored 135 days ago [-]
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.
tombert 135 days ago [-]
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 135 days ago [-]
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``.
jawns 135 days ago [-]
> 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 135 days ago [-]
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?
ryan-c 135 days ago [-]
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`.
These get styled such that they're black-on-black until you click on them. detail/summary doesn't work like that. Maybe with wild css hacks?
scott_s 135 days ago [-]
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.
strongpigeon 134 days ago [-]
I get that, but why not use HTML as the base to render to other formats? I guess I'm not 100% clear what you mean by semantic linking and how could that not be achieved through HTML.
scott_s 133 days ago [-]
If I understand you correctly, you want to throw out rST, and just have users write HTML directly? I see two issues with that:
1. HTML is designed for representing webpages, not books. Your intermediate representation will become HTML's DOM, which is likely not well suited to the book use case. You'll either need to use an existing HTML-to-DOM parser or build your own. One big limitation of the DOM, as I see it, is that it doesn't have the concept of a page number.
2. HTML is not extensible in the way the author talks about. This is the "semantic linking" thing I meant. In rST, you can define entirely new top-level constructs: he defines an exercise which has a solution and will be a part of a solution list. The semantic linking part is that other parts of the document will refer back to these solutions. Some output formats will have all solutions inline, with the exercises, while other output formats will collect all solutions in one place at the end. HTML is not flexible in that manner.
What is extensible is XML. It's entirely feasible for XML to be the input, but for better-or-worse, most people are even more turned off by XML than they are by something like rST.
strongpigeon 130 days ago [-]
> If I understand you correctly, you want to throw out rST, and just have users write HTML directly?
Yep!
> 1. HTML is designed for representing webpages, not books. Your intermediate representation will become HTML's DOM, which is likely not well suited to the book use case. You'll either need to use an existing HTML-to-DOM parser or build your own. One big limitation of the DOM, as I see it, is that it doesn't have the concept of a page number.
I guess my point is that while the main use of HTML indeed to render webpage, it seems pretty well suited at rendering most if not all types of documents. The page number issue you mention is typically only part of the presentation and is handled by the CSS paged media module (though admittedly, support of this isn't universal in my experience).
> 2. HTML is not extensible in the way the author talks about. [...]
Except it is! This is what HTML Custom Elements are all about. Combined with CSS, it can handled to different rendering formats you mention pretty well.
> What is extensible is XML. It's entirely feasible for XML to be the input [...]
I'd actually argue that raw XML is the wrong approach for most things, as the goal of XML is to be extended (e.g.: SVG, MathML, SAML, etc.). But I feel like that's a whole other discussion.
Anyways, I think this is a good conversation and wouldn't mind continuing over email (see my profile). It's fine if some people like rST, but HTML seems better suited for these use case than people make it out to be.
scott_s 127 days ago [-]
I'm less likely to continue this conversation over email. Such is life. :)
I think that bringing in CSS is a bridge too far for the case of writing a book. Authors are no longer just writing HTML, they're writing HTML and CSS. And CSS is intimately tied to actual web browsers - you're now going to need a browser display engine to be an integral part of how you render your book. (Or you're going to need to implement just enough of that yourself, which is a big undertaking.)
The point of comparison is Markdown, which is relatively straight-forward and simple. HTML and CSS is not that.
eddd-ddde 135 days ago [-]
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.
osmarks 135 days ago [-]
Preserving the semantic content is helpful if you think you might want to switch the rendering later.
PaulHoule 135 days ago [-]
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 135 days ago [-]
> 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 135 days ago [-]
> 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 135 days ago [-]
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 135 days ago [-]
> 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 135 days ago [-]
> 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 134 days ago [-]
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".
lmm 134 days ago [-]
A certain amount of namespacing is useful, but the XML model where you can't even write a hello world xpath query until you've set up all your namespaces and used them in your query is something that clearly does more harm than good. Java is I think widely recognised as having gone too far on the namespacing front; most post-Java languages have a much less strictly hierarchical namespacing model and I don't think any other package registry has adopted the fully nested style that Maven does. And even Java's heavyweight namespacing is much easier to work with than XML's thanks to things like auto-import in IDEs.
I don't think namespaces solve the macro hygiene problem, because if you're going to have macros then they need to be able to interact with and manipulate your namespaces, and sooner or later you need your macro to e.g. generate a fresh identifier for use within an existing namespace and then you're right back where you started.
Being able to disambiguate when you have one document including another would be useful. But the cost/benefit on XML-style big namespacing up-front just doesn't stack up.
SoftTalker 135 days ago [-]
Yeah I always liked XML as a data format and combined with XSLT it is quite powerful.
PaulHoule 135 days ago [-]
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.
tannhaeuser 135 days ago [-]
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.
_heimdall 135 days ago [-]
Once you get that far, XSLT is waiting for you if you need to render XML to HTML.
andrewflnr 135 days ago [-]
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.)
PaulHoule 134 days ago [-]
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.
andrewflnr 134 days ago [-]
I don't know. I liked the pattern matching, it was more the XML aspects that ended up not being worth it.
_heimdall 135 days ago [-]
Same. I've used it for small projects, like styling an RSS feed. I imagine it gets tricky fast in anything larger.
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.
Ah, you want something like pandoc, but you can manipulate the internals as needed?
PaulHoule 135 days ago [-]
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 135 days ago [-]
Sounds like an actually good use case for an LLM with RAG.
euroderf 135 days ago [-]
rST and Asciidoc seem roughly equivalent in terms of capabilities. Are they roughly equivalent in terms of weaknesses and missing features, I wonder.
bobbylarrybobby 135 days ago [-]
I think they're about equal, although asciidoctor has bold italics, which rST does not.
__mharrison__ 135 days ago [-]
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).
complex_pi 135 days ago [-]
I can't test (no computer right now) but can't include directives achieve what you want?
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 135 days ago [-]
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).
that is one of the things I miss most about writing in rST, for sure.
innocentoldguy 135 days ago [-]
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.
photonthug 135 days ago [-]
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 135 days ago [-]
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.
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 135 days ago [-]
That's what I meant by instructions on automated deployments. MdBook generates HTML, so you don't need anything fancy to host it.
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.
justin66 135 days ago [-]
[flagged]
jerf 135 days ago [-]
Well, the simple mental hack for yourself is just to prepend all blog content, if not all content in general, with
#include <general_disclaimers>
and you'll find yourself much happier in life.
Speaking as one who actually produces blogs on rare occasions, I have to say starting every post with "This is just my experience and may not apply to you this is not a claim of global applicability this is just applicable to this circumstance you're the one who chose to read this I didn't force you" and so on isn't exactly the most compelling way to open a post.
Though I have to admit now I'm really tempted to add that into my post template in like 2pt font or something, just so when people on HN complain I can point them at it.
justin66 135 days ago [-]
But that's all beside the point - we're not talking about a "general disclaimer." (I am intrigued by how blurry the lens you look at the world must be, if you live by that "#include <general_disclaimers>" nonsense) People interested in the blogger's rather specific Markdown use case would be better served by a more specific title, as would the nine out of ten Markdown users who are not.
jerf 135 days ago [-]
No, I was just recommending it to you since you seem to be perturbed. I just give people a general measure of grace in their writing and it all seems to work out fairly well. You can try that as well, if you like.
justin66 135 days ago [-]
Your comment was quite condescending, and it's disingenuous of you to suggest otherwise. If this is all your idea of grace, I'd hate to see less than graceful.
By contrast, I was careful to criticize the title as clickbait, not the post, which is useful (or the book, which sounds genuinely interesting). I wasn't perturbed by the title. By your comments, sure, but that's your doing, not Hillel's.
12_throw_away 135 days ago [-]
If the title "Why I prefer rST to markdown" (which a 100% accurate summary of the content) is somehow "clickbait", then the term "clickbait" has been redefined into meaningless.
justin66 135 days ago [-]
I mean, which of the following is more precise?
"Why I prefer rST to Markdown"
or
"Why I prefer rST to Markdown for Typesetting"
Since it's a clearer statement of the author's meaning, and since very few users interested in Markdown are going to be doing any typesetting, it seems like a more meaningful title to me.
But less likely to draw in readers... to "bait" them, if you will.
keybored 135 days ago [-]
Subjective preference is not clickbait.
necovek 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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.
If you want to use a mark-up language in a chat app, a subset of either would serve you just fine and both are equally simple. It sounds like you are comparing a subset of what-is-markdown-today (and there are still variants) to full reST, which I don't think is a fair comparison.
From a very brief look, here's some things that probably aren't generally necessary (and aren't included in Markdown): Document structure, Bibliographic fields, complex footnotes and citations, directives, substitution definitions
All of these increase the number of things I have to escape, as well as my cognitive load when writing documents. And that's before we talk about reST config settings!
You could use a subset of reST, or you could just use Markdown!
lmm 135 days ago [-]
> 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 135 days ago [-]
I guess you must really hate the double * for bold in either.
lmm 135 days ago [-]
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 134 days ago [-]
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).
ktosobcy 135 days ago [-]
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…
IshKebab 135 days ago [-]
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 135 days ago [-]
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.
YakBizzarro 135 days ago [-]
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
FartinMowler 135 days ago [-]
I run asciidoctor's Docker container. It does what I want it to do without leaving a mess behind on my laptop.
IshKebab 135 days ago [-]
The trouble with that is it becomes a pain in CI. Nested Docker isn't fun.
IshKebab 135 days ago [-]
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 135 days ago [-]
the toc macro on asciidoc is sublime
:table-caption!:
:toc: macro
:sectlinks:
toc::[]
__mharrison__ 135 days ago [-]
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 135 days ago [-]
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__ 134 days ago [-]
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.
teamspirit 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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.
wodenokoto 135 days ago [-]
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 135 days ago [-]
> 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 135 days ago [-]
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.
mg 135 days ago [-]
Markdown:
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:
[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 135 days ago [-]
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 135 days ago [-]
(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.)
Ericson2314 135 days ago [-]
OK that specific example works, but what about his later problem vs solution one? One runs out of hacks pretty quickly.
romanovcode 135 days ago [-]
Honestly I stopped reading article after this example. No, thank you. RST syntax looks confusing and overly explicit. I'd stick with MD thankyourverymuch.
joekrill 135 days ago [-]
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 135 days ago [-]
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.
benji-york 135 days ago [-]
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.).
bunderbunder 135 days ago [-]
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 135 days ago [-]
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.
Macha 135 days ago [-]
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 135 days ago [-]
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.
Macha 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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...
osmarks 135 days ago [-]
CommonMark mostly fixes this.
xigoi 135 days ago [-]
At the expense of being extremely complex.
marcosdumay 135 days ago [-]
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.
Karellen 135 days ago [-]
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 135 days ago [-]
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:
Not having used djot myself, does “rethink tight/loose lists” refer to that?
0cf8612b2e1e 135 days ago [-]
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 135 days ago [-]
Indeed; Github will now render TeX in markdown documents, eg when displayed as a repo's readme. Very convenient.
smore 135 days ago [-]
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.
SparkyMcUnicorn 135 days ago [-]
I believe Mozilla uses rstcheck for linting, and it's actively supported.
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.
karaterobot 135 days ago [-]
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.
louwrentius 135 days ago [-]
The one-line summary is:
> I think Restructured Text is better for writing books than Markdown.
That would be a better title.
meribold 135 days ago [-]
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…
remram 135 days ago [-]
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 135 days ago [-]
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.
xigoi 135 days ago [-]
> 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)?
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.
hwayne 135 days ago [-]
Yes, and this sucks.
thesnide 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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.
prpl 135 days ago [-]
Sphinx + markdown (Myst) is a nice middle ground here I think, with the sphinx directives implemented as code blocks.
keybored 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
Why is your username not capitalized, Keybored?
keybored 135 days ago [-]
Poor self-esteem.
queuebert 135 days ago [-]
Personally, besides it being a nice format, I use Markdown to honor Aaron Swartz.
Ericson2314 135 days ago [-]
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
tristor 135 days ago [-]
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.
Analemma_ 135 days ago [-]
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 135 days ago [-]
> 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.
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
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 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
Hugo/Jekyll/etc. all work the way GP described too.
arp242 135 days ago [-]
> 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.
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 135 days ago [-]
> 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.
asmeurer 135 days ago [-]
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.
ideasman42 135 days ago [-]
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.
romanovcode 135 days ago [-]
I think author should write HTML if they want extensibility so much. Not like RST is reading-friendly to begin with.
ideasman42 135 days ago [-]
Keep in mind you might not _only_ be exporting HTML.
kaizendad 135 days ago [-]
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 135 days ago [-]
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).
fefe23 135 days ago [-]
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 135 days ago [-]
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 135 days ago [-]
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 134 days ago [-]
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.
paholg 134 days ago [-]
As you said, it's not static. You can update the content of pages.
You can also reorganize things and keep old links as 302s.
At a minimum, you should be aware of when you're breaking links and it should be a conscious decision.
red_admiral 134 days ago [-]
The way of the world is this: ISO comes up with SGML, everyone gets a pat on the back, and then some guy called Tim who isn't even on a standards committee comes up with some bastardised version where you have to use angle brackets rather than generic customisable delimiter classes, and there's things like `<b>` for bold that are not even semantic. Guess which one took over the world?
I write a lot of markdown at work, and while you can't do this in commonmark, most parsers will absolutely let you define custom block types and transform the doctree and other things. You know how three backticks followed by the word 'python' produces syntax-highlighted code almost everywhere? You bet that I can do `::: warning` in my documentation to make the following content appear in a big red box with an exclamation mark.
As long as you don't put raw HTML in your source, you can even render to different targets like PDF. jupyter-book is a good example here.
wiresurfer 135 days ago [-]
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.
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 135 days ago [-]
Out of curiosity, would you be able to write a parser that uses the markdown style for image links?
breck 135 days ago [-]
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.
concombres 135 days ago [-]
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 135 days ago [-]
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!
runningmike 135 days ago [-]
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.
gregopet 135 days ago [-]
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.
mrled 134 days ago [-]
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.
Ignores newlines (turns single newlines into spaces) so just as annoying as markdown for me. I'm looking for a text format that has some formatting ability, but preserves newlines you enter. BBCode is a good one.
What makes so many designers of these plain text formatting languages choose to not preserve newlines? I don't get it. Preserving newlines is one of the main features of plain text.
This causes the same annoying thing as hacker news comments do, like this intended multiline shopping list:
-eggs
-flour
-milk
-sugar
-salt
fireflash38 135 days ago [-]
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.
aidenstern 134 days ago [-]
What kind of compliance? I’m working through the same thing right now and trying to decide between sphinx and mkdocs
fireflash38 132 days ago [-]
Common Criteria. Stuff that needs insane amounts of documentation of your testing.
mjburgess 135 days ago [-]
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.
blt 135 days ago [-]
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".
hintymad 135 days ago [-]
> .. 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?
somat 135 days ago [-]
"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 135 days ago [-]
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.
bluGill 135 days ago [-]
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)
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.)
jasonpeacock 135 days ago [-]
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
skybrian 135 days ago [-]
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.
taeric 135 days ago [-]
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.
HenriTEL 134 days ago [-]
To me the main deal breaker with reST is titles that must be underlined with punctuation characters at least as long as the title.
That's very annoying to write, and some people even add overlining.
We're entering the ascii art domain here and I don't have time for that.
geenat 135 days ago [-]
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.
zelphirkalt 135 days ago [-]
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.
beej71 135 days ago [-]
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...?
gigatexal 134 days ago [-]
I’m not convinced. Markdown is cleaner imo and basically the standard. I see no reason to move.
JoshTriplett 135 days ago [-]
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.
xixixao 135 days ago [-]
This is why MDX rocks. It doesn’t have all of this builtin, but you get a lot of the same benefits.
insane_dreamer 135 days ago [-]
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.
135 days ago [-]
daghamm 135 days ago [-]
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 134 days ago [-]
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.
Morizero 135 days ago [-]
> 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?
betaby 135 days ago [-]
asciidoc anyone?
schaefer 135 days ago [-]
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 135 days ago [-]
+1. My current workaround is the use of asciidoctor to convert my docs to docbook. This format is supported by pandoc.
papascrubs 135 days ago [-]
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:
Asciidoc solves nearly every problem I've ever run into with markdown and RST. I really wish it were more widely adopted.
KronisLV 135 days ago [-]
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.
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.
dheera 135 days ago [-]
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.
wiseowise 134 days ago [-]
> I can't get into lisps for the same reason.
I assume they’re talking about s-expressions? Then that’s a really bad example, because those are objectively beautiful.
psychoslave 134 days ago [-]
What are the objective criteria in that case?
135 days ago [-]
fridder 135 days ago [-]
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.
bradboimler 135 days ago [-]
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.
Ericson2314 135 days ago [-]
I am proud to say this is might be the first time I finally agree with Hillel Wayne and something (at least mildly) controversial.
mmphosis 135 days ago [-]
I prefer What You See Is What You Get (WYSIWYG.)
port19 134 days ago [-]
So it's more complex than markdown while being less powerfull than latex or org-mode?
What a waste
rk06 135 days ago [-]
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
fermigier 134 days ago [-]
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.
> ...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.
Animats 135 days ago [-]
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 135 days ago [-]
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.
unoti 135 days ago [-]
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.
AceJohnny2 135 days ago [-]
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.
remram 135 days ago [-]
What's the YAML syntax for "That's a _weird_ idea, [YAML](https://yaml.org/) is a data serialization language"?
RomanPushkin 135 days ago [-]
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 135 days ago [-]
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.
paxys 135 days ago [-]
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 135 days ago [-]
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.
0xbadcafebee 134 days ago [-]
My grandmother can create better docs than most programmers, but not because she's some technical wizard. She uses MS Word. Imagine, a program designed to allow humans to lay out and format a document quickly and easily... programmers prefer to hack up ascii art and forego the graphical layout and formatting tools developed 30 years ago. And then they complain that docs are hard to read/write...
kstrauser 134 days ago [-]
Grandma’s doc may not be readable in 30 years. I can look at basically every text file written since ASCII came along with standard tools. Also, since Grandma isn’t a programmer, she’s probably not collaborating on her doc with a bunch of distant people using a version control system with patch requests.
Shiny tools are nice when it’s only you and you don’t need to keep the results forever.
0xbadcafebee 133 days ago [-]
Lol, dude, Word files have been readable by open source tools since forever. MS Word itself supports many different formats including OpenDocument, so there is absolutely no problem with being able to read them in 30 years.
MS Word supports version control, but patches are a terrible idea for documents. Again, the whole point of a document is to make it easy to read, so the formatting becomes a huge pain in the ass for a patch. Patches are designed for lines of code, not the formatting, layout and content of rich text documents. Trying to force documentation to work like code is making the computer happy, rather than the computer making people happy. It's the opposite of what technology is supposed to be for. Think about what you're spending your life on. You gonna look back when you're 80 and think, gosh, I'm so glad I spent those extra hours going back and forth with a dozen people on the internet to try to approve an update to documentation? I'm so glad I spent an extra hour tweaking this program code so that this document would have an embedded table aligned right? I'm so glad I had to write a separate program to be able to format this Markdown Table so that I could actually edit and save it so that it renders?
Docs should be living / not require requests for patching. Humans should be entrusted to just update a document immediately, with a log and comments to allow reverting entries only if necessary. Aka a wiki (and a WYSIWYG one at that). The whole purpose of patch requests is not to gatekeep information, it's to make sure a change doesn't blow up a program. Documentation isn't a program, just change the document.
Kwpolska 134 days ago [-]
Word sucks if you want consistent formatting. It has styles, but they randomly glitch out and can't always handle everything. I want docs in HTML, not PDF, and definitely not DOCX. The issues some programmers have are issues with content, not formatting.
nailer 135 days ago [-]
"Now here's how to make an image in rst:"
.. image:: example.jpg
:alt: alttext
Great, I can close this article now.
numlock86 135 days ago [-]
> 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.
kelsey98765431 135 days ago [-]
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.
morbicer 135 days ago [-]
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.
psychoslave 135 days ago [-]
>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.
>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.
Rendered at 22:11:55 GMT+0000 (Coordinated Universal Time) with Vercel.
Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant.
Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax.
I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
But then I realized, after using it in some apps, that wasn't really what Markdown was about. Markdown is about a bare-minimum amount of styling that is just as readable and at home in plaintext as formatted in HTML. The amount of formatting it supports is small _on purpose_, so that it fits in your brain and doesn't require a toolbar to use. It is _meant_ for things like comment fields, chat programs, commit messages, and so on. Maybe even blog articles. But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.
These days, I write Markdown even in place where it will never be rendered into HTML. Because it's quite readable as-is. (And I wish HN supported it.)
1. Apparently simple enough to implement to get the basics right (not that I could do it)
2. But there is plenty of room for accidental edge cases in the implementation
3. Many then implement it with or without edge cases
4. But it’s not enough because a lot of the people who use it are programmers so they naturally want to extend it to do just a little more
5. Now the standardization effort (Commonmark) has to take all of those edge cases into account plus have to figure out how to deal with extensions (especially for popular ones)
6. Then you get a heroically (in terms of effort and grit) wordy standard
All for the initial idea which is so simple that it seems redundant: look as good plain as rendered. (Then what’s the point of rendering it, and in turn what’s the point of a formal syntax instead of the (still existing) ad hoc email and whatnot conventions?)
Right now it’s fantastic for chat applications (here you definitely want rendering and not the visible markup). It’s been pretty good for things like forum comments as well. With the exception of block quotes which are a pain to fiddle with (the only prefix syntax if you don’t include the indentation-for-code since that is de facto optional now that so many applications support code fences… all because that’s how email does it).
> it’s fantastic for chat applications
Slack is the absolute worst at it; I am unable to at all figure out what its "parser" (which feels like cobbled together regexes … but even then … not?) is doing.
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.)
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.
If someone hits control+I, or an italics button, it should use <i> tags, not <em>.
What about * for bold, / for italic and _ for underline?
If people want to make foo or foo bar italic, they write /foo/ and /foo bar/.
Perhaps //italic text// would be acceptable.
I, myself, prefer /italics/, _underline_ and _bold_ in text, if there is no formatting. I feel that these 2 are the least arbitrary, they almost work without agreeing on their meaning beforehand.
And for technical stuff I very often have to edit my message.
And yes: don’t even get me started on having to think about whether I can write a link or whatever in MD or if I have to use the bells and whistles buttons in Slack.
Considering that Slack is used by both technical and non-technical users they should, well, really have a way to toggle between rendering the text immediately while typing and having it in the raw form while typing. Because editing it raw would be much less confusing for me.
This is actually an option in the settings (on desktop, at least).
It's intended to look as good as possible in both mediums. It is not possible for the raw text to look as good as the rendered text and still be easily writeable, because the raw text cannot generate visual hierarchy using font size and weight.
I suspect you know this, but when you say readable raw text seems like a redundant idea, I'm not sure what point you're trying to make.
I was referring to the sentiment that “MD looks so good that I might never even render it”.
You need inline html fairly often for anything non-trivial, and some of the rules certainly aren’t intuitive or easy to remember.
That said, like JSON, it won by being both simple to grok and good enough for most use cases.
Markdown is... limited, I acknowledge. But with a very small amount of learning, markdown is as fluent and simple to write as normal text. In fact, 90% of what I wrote before I knew markdown was valid and decently formatted markdown already.
If you asked people who don't document to document in rST or tex... then you'd have no documentation at all. Because that suddenly adds a lot of effort on top of what you want to write down.
Now for some customer-facing whitepapers and documentation, we do use rST. But there you have people who are tasked with paying some effort to create some decently looking docs. Not trying to coax developers into writing down some of their state of mind while doing stuff.
Markdown is great because it is a way to write and store documentation in plaintext, in a way non-documentarians can follow.
Bingo!
My gripe is that it really isn't. Because markdown inevitable includes images or something and the instant it does it doesn't hold up to it's killer feature. Now you can't read it properly, so now you have to find a generated version, or hunt down the images manually, or generate the output yourself.
Alternatively, the document is so trivial that even markdown formatting is too much (just distracts) and doesn't add anything of value.
It isn't that bad, it just never seems to make any sense for files. It does make sense for web forms though but that's only because you never read the markdown, you just write it and the output is generated on the fly.
The alternative is WYSIWYG formats that aren't plain text.
I'm gonna be annoyed if I clone your repo, open the readme.md and now have to figure out how to read it.
Plain text is awesome, for plain text. If it isn't plain text might as well use a pdf.
Maybe, just maybe, looking at that image is a good idea to do before reading 20 pages of documentation? Probably a good idea to look at even if you only intended to glance at the documentation for 20s.
Because that's what markdown mostly is in my experience, documentation. And the images, if they exist, often are a very important part of that.
Now some images are garbage, but you don't know because the alt-text will not be "Superfluous image that doesn't add to the understanding". Maybe it depends on the reader, is the reader fluent in design patterns (and crucially, is the project following the design pattern as is or have they made their custom modifications to it?).
But in reality it will likely be a flowchart. Kind if an important piece that really help when reading the text. Or maybe just an image of a header and all the field sizes. Can you do it without it? Sure. But remember that not all documentation is perfect, it might not have had someone pouring his/her heart in it. It might have been rushed. So as often is the case you actually do need both the image and the text, not just to help understanding (which alone really is reason to make sure you look at both) - but because you need both to get all the information.
I sigh when I see a .md. Especially in documentation, because in reality that probably means that I have to either get the dependencies and look up the build process to build it myself. Or I have to go to the official project web page and browse the documentation there.
If it is a .txt or .pdf I know what I'm in for, and I know I have the tools needed to view it.
(you know you can write paths in a .txt file too?)
We use markdown because it is plaintext and accessible. Oh, but you have to convert it yourself. How? Well every project is different but I'm sure you can find a Makefile somewhere in the project. Good luck!
Again, the point again is that markdown is not readable alone.
If it is, then a .txt is strictly superior. If it is not, then never, ever, present it as the final product. Always ship the generated artifacts. The only point you want to actually see the .md file is if you want to make changes to it. Is making changes the primary usecase for your markdown files? I'm going to assume, no.
I edit a number of wikis. This leads to an inevitable amount of instances of having images floating aside the the text. Sometimes there's some peculiar stuff done with tables. But we never actually intermix the text content in a completely unreadable way, at least outside of templates and modules, which are NOT text content meant to be read in the first place and are NOT markdown either.
Every section of text only has text content, and the only alterations to the text come as syntax that strictly surrounds the affected text. If images have peculiar formatting demands, they will exist outside of text (Such as a CLR).
I guess that depends. If you're making a print manual, yeah probably not. IME markdown gets painful as soon as you start doing a bunch of tables.
Most enterprise web applications would probably be completely fine with just markdown-based docs.
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
That doesn’t mean that I think Markdown is inadequate or the wrong decision, but it’s not just a “write in Markdown and you’re good” sort of situation.
I'm investigating how to switch an organisation away from a docx-only mess of a documentation system, and it looks like you might have found a process that'd work for us, and let people keep using docx if they have to.
I wonder what all those binary blobs do to the git repo though.
Thanks for any info!
From my perspective, the markdown was the master copy.
Sorry I can't be of more help!
MDN documentation is written in markdown. I’ve always felt this was a resounding endorsement of markdown over other more “powerful” markup languages because if they can do it, why can’t you? (not you in particular, but anyone who thinks markdown is inadequate for docs)
https://developer.mozilla.org/en-US/docs/MDN/Writing_guideli...
I'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
* 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...
The biggest issue I have seen with TeX is a people problem: people frequently write spaghetti TeX with horrible style. This is terrible, but it is not actually a language issue. Writing it with a "docs are code" mindset can produce some very clean results. The second biggest issue is that there isn't a good TeX -> HTML compiler.
reStructuredText isn't itself a typesetting language. It's meant to be something of an interposer between the semantic meaning of what you're writing and the thing that does the typesetting. The hope is that it, unlike something heavily constrained like Markdown, gives you the tools to capture that semantic meaning and transform it into something that can be typeset.
Like, the goal isn't to throw out TeX. The goal is to be able to target TeX as a typesetter along with Web browsers and e-book readers and even things like GNU info and troff without having to rewrite the content wholesale to fit each one.
Modern web pages are already designed with "camera ready" in mind, essentially with browser width being the only thing that changes layout.
I just wish the typst compiler had a way to output html. It would be perfect for making online documentation and blog posts.
https://github.com/cetz-package/cetz
I suppose that makes it inappropriate for something like rendering comments, but it's a great way to write documents. I used it a lot for writing papers since there's a lot less boilerplate and was much easier to use than TeX.
I find LaTeX to be the lesser of evils when creating PDFs. However, I rarely deal with LaTeX issues these days because all of the pain points have been patched away in my tooling that converts md to tex. However, I keep thinking something more modern or faster (like Typst) might make my life as an author easier. Compiling LaTeX with tools like rubber is still painful and slow.
1. Separate each part of a document into different TeX files and include them in the main document. Each file should be a separate unit of the work. Only compile the main document when you need to.
2. Generally write with readability in mind and use newlines and other whitespace in the source a lot more than you think you should.
3. If you have common boilerplate that you frequently use at the top of docs, make your own package(s) for those commands and maintain that separately.
4. Refs and labels everywhere you possibly can. Also, prefixing your label names helps a lot, so \label{clouds} on a picture of clouds becomes \label{fig:clouds}. If you are writing a book, and this is the chapter on the sky, consider \label{fig:sky:clouds}.
Also, is there a book that you would recommend for learning LaTeX?
I'm not sure if there is a good book on LaTeX, ironically.
To me this seems a horrible decision at the stage of writing/structuring. I'd rather write in Markdown (this way I could just write, without bothering about typesetting) and only convert to LaTeX for publishing. I'm not proficient in LaTeX though - I once tried to learn it and it felt like learning a language of an insectoid extraterrestrial civilization - completely unintuitive, almost impossible to do anything new - what hasn't been already done by someone else enabling you just copy-paste your own text. IIRC it doesn't even have first-class Unicode support.
Macros are also pretty easy to define \newcommand\important[1]{\textcolor{red}{#1}}
And of course it has first-class Unicode support
https://typst.app/docs/reference/foundations/function/
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.
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
This has always baffled me. _underline_, /italics/, bold.
But also asterisk is a common form for multiplication just like / is for division/separation (which is more common than paths)
So you already have this design issue, but on the other hand at least you could have the benefit of visually intuitive markup, which isn't the case with markdown
Multiple multiplication signs can be used with spaces, x * y * z.
Markdown makes no mention of italics. It speaks of emphasis and strong emphasis. Underscore and asterisk are interchangeable, doubling gets the strong variant. Using slashes for italics doesn't fit into that scheme.
Yeah, I'm fine with that, it's a bad original design decision to waste two symbols for the same thing in the first place, and the subtle _foo_bar vs foobar differences go against the simple nature of the markup
All these _foo_bar intricacies should be dealt with via escaping (or an even better alternative design of using some other marker types like _[] to allow free use of the marks)
> Using slashes for italics doesn't fit into that scheme
Sure, because that's a bad scheme, and not mentioning such a common thing as italics doesn't help either since the whole point is visual intuitiveness, so markdown still fails here (and adds a needless cost of 2 extra symbols "for the strength")
> Underscore and asterisk are interchangeable, doubling gets the strong variant.
But you've just shown that they aren't
That's programmer-think, while markdown was meant to cope with existing conventions as much as possible. Markdown was primarily a pragmatic thing that worked with people writing without needing to think of many rules, and that's exactly why it got so popular.
Wanting /italics/ is just your opinion, not some objective ideal.
> Markdown was primarily a pragmatic thing that worked with people writing without needing to think of many rules, and that's exactly why it got so popular.
That's wishful thinking, the whitespacing, especially in such common thing as lists, is something that requires thinking. And with urls it's a common fail to forget which () [] go where. And there is nothing pragmatic/conventions about this strong/emphasis nonsense, that's just following HTML <em> spec, none of common email/blog post plain text writers think in HTML standard, they think in terms of bold/italic/underline
> Wanting /italics/ is just your opinion, not some objective ideal.
Wanting is not an opinion, it's a desire. Also /italics/ is objectively more intuitive
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.
Do you really read Markdown in plain text editors? I only do occasionally (nevertheless I'm glad I can). Most of the times I use tools like Obsidian, Typora, Markdown Monster etc.
HTML is just too bad for plain source reading relatively to Markdown and too complex for reliable mapping between what it is looks, what it means and what it is.
This said, something slightly more complex than Markdown while slightly more elegant, less chaotic and more readable than HTML sounds a great thing to have.
There certainly are cases where Makrdown seems the best choice - wherever simple plaintext editors are going to be used often. Nevertheless I doubt Markdown is the best choice for tools like Obsidian - perhaps people working on new projects of this kind should also take a look at rST or AsciiDoc.
Revive Textile? It was one of the inspirations for MD, IIRC.
100 times yes. Markdown for light styling. LaTeX for anything else. The next revolution in standardized text parsers will not come from replacing Markdown, but from replacing LaTeX.
There is a big gap between a book and informal notes, docs, comments though. At least big enough to drive several tools into, or they wouldn’t exist.
Even if rst has a generic extension mechanism, on github you'll spend a lot of time referencing commits, tags, users, pull requests and that kind of thing. So you end up having to know a domain-specific language anyway, whether it's formally presented as an extension mechanism to the language or as a dialect.
You'd want to use Typst, not LaTeX. I'm rewriting my CV with it, it's fantastic. I can now finally put the CV contents in a JSON, and generate the PDF programmatically, with lots of computed values by my own algorithms, the layout is simple, nothing stands in the way, nothing feels out of its place. And compilation is so fast... Really, forget LaTeX, embrace the 2020s.
> ..Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I'm not going to begrudge anybody who avoids a tool because it's ugly.
To me, they are largely the same thing, with slight syntax differences, with reST being more readable as it's clearer what any special syntax is about, whereas MD is more concise to type out — you need to learn the special syntax whatever way you slice it.
FWIW, reST was the default for Python "doctests": a wonderful feature that has fallen out of favour for some reason, but has the potential to be your real runnable documentation.
I wouldn't write a book in either, but that's because I am really high on great typesetting — I even had my own set of (Plain) TeX macros to do ToC generation, syntax highlighting, alternative math fonts, support for UTF-8 before eTeX and such when I did write papers and handed in coursework regularly.
It isn't though. It's just a whole lot more annoying. On paper the syntax differences are small, but they make the writing experience so much worse. I wanted to like rST but it just isn't good enough in use.
(I still like doctests and use them extensively in my books.)
>...Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I'm not going to begrudge anybody who avoids a tool because it's ugly.
Markdown is pretty bad for note taking, it has a niche functionality suited for basic text based note taking. Unfortunately that isn’t the only note taking that is possible
reStructuredText (reST) by itself can be pretty rough. reST combined with Sphinx is pretty great. I.e. the strengths of Sphinx far outweigh the weaknesses of reST. For big, professional docs sites (+100 pages, +10 contributors) I have pretty strong opinions that Sphinx is probably the most responsible choice, long-term.
> The most important difference between rst and markdown is that markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree.
Yes, what this means in practice is that it's easy to customize common aspects of your site (such as how images are displayed). A teammate of mine on Pigweed recently created a shortcut for linking to bugs consistently. You type :bug:`59385981` and the link gets transformed into https://pwbug.dev/59385981. If we ever need to mass-migrate all of our bug links, it's now trivial. Another profoundly important consequence of this architecture: all internal links are guaranteed to always resolve (you get warnings/errors if you link somewhere that doesn't exist). I previously wrote about how baffling it is that this is not the industry standard for docs sites: https://technicalwriting.dev/src/link-text-automation.html
The other thing that Sphinx excels at: well-defined extension and theme APIs. It's not exactly easy to build extensions or themes, but lots of people have figured it out (including me). There's a pretty rich ecosystem of extensions and themes on PyPI.
Lately I've been calling Sphinx the sleeping giant of docs systems. It's already pretty great and with a little concerted effort I think we can collectively make it absolutely phenomenal. The upstream Sphinx repo now has a GitHub Discussions section that gets a little traffic; a lot of us seem to congregrate on the #sphinx channel in the Write The Docs Slack.
This, so much this.
It's a problem in an even more general form (for you're writing about linking to sections within a page): the number of CMS systems or static site builders that make you insert the final URL when you write is _insane_.
If the slug changes, you reorganise your site - now you have to do a search and replace through the site to update all your links.
Static site generators could enable linking like [Hello](../hello.md) and resolve the link at build time, instead of expecting everyone to type [Hello](/why/hello/). And yet the popular ones I've used or looked at don't do this.
It seems to be a marmite feature (you love it or you don't): I've raised it with static site builder team members and received a "Why would you want that?" response. Explanations got nowhere. I'm not sure if it's a niche feature, you have to have experienced the problem to appreciate the solution, or people are used to writing once and not maintaining for a decade or longer, but it'd be great to see wider support.
I'm not a fan of reStructuredText, but nowadays it's possible to do most things that previously tightly coupled Sphinx to RST in Markdown, courtesy of MyST-Parser: https://github.com/executablebooks/MyST-Parser
I found this to be very easy using Markdown+pandoc. I turned image tags containing youtube links to thumbnails with video tag and alt text, hooked up image tags to local video files to ffmpeg to optimize and resize videos to then do the same, etc in a few lines of code.
I just ported a 200+ page book documenting an internal language/VM/abstraction-layer to Sphinx ... holy moly, this is a life changing system!
I wish the documentation for Sphinx, itself, had a lower ramp and/or more examples; otherwise, I'm still in a pretty fantastic honeymoon phase.
My two main lines of research are how to build good looking PDF (books); and, some sort of system to let me cut a book into POSIX compliant man pages by chapter/section.
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
However I'd push back a little. That Fluent UI doc site looks like every other doc site from an open source project started since ~2020 that I've seen, and this means that I have certain expectations: I expect the project to be immature, I expect the docs to be incomplete or out of date, I expect the search to be an annoying AI search that does a worse job than the basic full text search that I expect elsewhere, I expect that to get anything of substance done I'm going to have to hang out on a Discord server. When I see a ReadTheDocs site though with that default theme, I expect the project to be somewhat mature, I expect it to basically work. I expect the docs to be fairly complete.
Are these expectations fair? Not really, but that's the whole point here. Open Source projects are not immune from marketing, and when marketing, what other similar projects do will affect how people respond to your marketing. Nothing exists in isolation.
In my experience, engineers think marketing doesn't apply to them, but these impressions really do matter.
One nit: I called Sphinx a sleeping giant because it's already majorly successful in the Python ecosystem. Pretty much all big Python docs sites are built on top of Sphinx, including docs.python.org. But I think it's fair to say that when Sphinx starts getting major adoption outside of the Python ecosystem then we can start calling it a breakout success.
I'll ignore Apple because: 1) It loads _extremely_ slowly (10+ seconds). 2) Just looks like a dark theme and nothing more.
The featured themes, in general, have poor typography and whitespace, poor formatting and alignment, and uninspired colors and design. Furo [0] is the best-designed of them and would make a solid foundation for a proper theme.
[0]: https://sphinxthemes.com/themes/furo
[1] https://pigweed.dev/#what-is-pigweed
The first part didn't really do it for me because it seemed too meta:
"Over 150 libraries" - to do what? (Actually, some good examples are in the next section.) "Automation" - to build, test, and lint what? "Environments" - to make builds reproducible, to do what? "Frameworks" - turnkey solutions for what?
They are clickable, though, so maybe I should have clicked. :)
> We provide libraries (modules) for strings, time, assertions, logging, serial communication, remote procedure calls (RPC), and much more.
Maybe put that up front?
Looks like "frameworks" are still work in progress; maybe I'll check back someday when they get to Raspberry Pi Pico support.
At my last job I spent a fair amount of time on documentation, but I don't have a great understanding of what technical writers like/dislike, or what documentation systems are best.
So, you've made a convincing argument of why we should prefer Markdown to reST, 9 times out of 10. If we're working with Sphinx we'll give it serious consideration.
So yeah, I don't really have strong opinions on sticking with rest per so. I only have strong opinions about Sphinx being probably the best choice out there for large docs sites.
[1] https://myst-parser.readthedocs.io/en/latest/
This is my main problem with the article, as this is decidedly incorrect.
Markdown was designed as a tool of conversion of de facto standard of formatting text in email messages and Usenet posts of early nineties. The basic 7-bit ASCII nature of those technologies inspired people to informally annotate the text with special signs to denote formatting like emphasis, section titles and the like.
True, HTML shares a lot of similarities with that nameless standard, so John Gruber in 2004 wrote a basic script [0] to convert the latter to the former, never expecting it to become such a universally used actual standard.
[0] https://daringfireball.net/projects/markdown/
Gruber did not take a "de facto standard" from Usenet and simply write an HTML converter for it. He designed his own markup, borrowing from Usenet and other conventions. The “Acknowledgements” section at the bottom of your link alludes to this fact.
Markdown was from the beginning intended as a markup syntax for web CMSs. To say it is a lightweight representation of HTML is correct. The whole point was that every part of the syntax produce a direct HTML equivalent.
> To say it is a lightweight representation of HTML is correct.
It's correct in the context of (2) but not (1). In the context of (1), Markdown is a lightweight markup language for rich text. For example, Pandoc can convert Markdown to formats like PDF, LaTeX, and ePub.
This is made abundantly clear on the Syntax page[0]:
> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.
> Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.
> For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.
Markdown is very coupled to HTML, and is hobbled as a result compared to formats like Tiddlywiki and Org that not only have sophisticated syntax for all kinds of content like tables, but also directives to the parser itself to render particular blocks using an external tool. I wrote a bit about this in 2021 in response to query about why Org mode doesn't use Markdown[1].
[0]: https://daringfireball.net/projects/markdown/syntax
[1]: https://rpdillon.net/why-doesnt-emacs-org-mode-just-use-mark...
As a matter of history you're right, just as JSON was intended as nothing more than the literal syntax for JavaScript programs. But it turned out to be a lot more widely applicable.
> To say it is a lightweight representation of HTML is correct.
No, it's a representation of writing. It represents the input not the output.
The first few years after I released Markdown, it was far less popular than I expected and hoped it would be. But it grew, and then for a years it was as popular as I’d expected. But then it kept growing, and now it’s far more popular and widely used than I’d ever thought possible. I genuinely now think it’s used in many cases where it shouldn’t be, and exposed to non-technical users who should be using something WYSIWYG, not 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.
You can read a Markdown document pretty easily using "less" or any other character-based interface.
The same is not really true of reST.
Maybe I'm confusing that with some other plain-text markup convention?
this is clear from the fact that HTML can be inlined in a markdown document; this is part of the spec (in so much as there even is a "spec" for markdown, anyway).
Some Markdown parsers support some HTML. You cannot, for example, add a YouTube video embed to a GitHub comment. Webpages that allow Markdown quite reasonably limit what’s accepted.
On this question, it isn't.
Markdown qua Markdown, unambiguously supports HTML tags. You can verify that yourself: https://daringfireball.net/projects/markdown/
The introduction being:
> Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
It's not possible to read the original specification without agreeing that, yes, Markdown is specifically a way to generate HTML. It also has a nice syntax which has become popular in contexts where embedding HTML isn't a good idea, and there are some tools which allow Markdown to be converted to other formats as well (usually, but not always, these disallow most HTML tags, meaning that they aren't Markdown sensu stricto either).
I would say that all of this supports Hillel's basic point here: Markdown is in fact tied to HTML semantics, in a way which makes it painful to do things with it which aren't tied to those semantics in the same way. Dialects in the Markdown family exist which make this less painful, and they do so by diverging from the original Markdown spec.
The section I quoted (and responded to) didn’t say “Markdown supports HTML tags”, it said (emphasis added) “Markdown parsers support (…)”.
So unless you’re arguing that a tool cannot be considered a true Markdown parser¹ unless it parses HTML, the distinction is irrelevant. I wasn’t making a general argument, I was responding to a specific claim.
> You can verify that yourself
Yes, I am quite familiar with that subpar piece of code and specification. I have spent some time implementing a Markdown parser myself (the output wasn’t HTML) and Gruber’s resources were by far the worst. For various reasons he has been an awful steward of Markdown; its ubiquity is despite him, not because of. Forgive me if I don’t find the author to be the authoritative source anymore.
¹ https://en.wikipedia.org/wiki/No_true_Scotsman
> Markdown was designed…
Surely Gruber is an authority on that.
And anyway, “ markdown is a lightweight representation of html” is true enough that calling it “decidedly incorrect” is wrong. Certainly it’s not a point that’s supported by going to author intent.
Yes, I completely agree with that.
And that wasn’t the point I quoted or responded to.
> From the top comment
Again, I wasn’t replying to the top comment, I was replying to what I quoted, from the comment I replied to.
> 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.
- 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.
> the single biggest source of inspiration for Markdown’s syntax is the format of plain text email
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.
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.
I haven't used rST, but looking at the examples it looks considerably less readable out of the box.
To me, the whole point of markdown is to allow you to do simple things faster than writing raw HTML, but with the ability to intersperse raw HTML when needed.
In projects where I've needed the power of RST over markdown, I've felt more comfortable just writing raw HTML directly.
> This means you can extend Sphinx with new text objects! Say you that instead of an <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?
1. HTML is designed for representing webpages, not books. Your intermediate representation will become HTML's DOM, which is likely not well suited to the book use case. You'll either need to use an existing HTML-to-DOM parser or build your own. One big limitation of the DOM, as I see it, is that it doesn't have the concept of a page number.
2. HTML is not extensible in the way the author talks about. This is the "semantic linking" thing I meant. In rST, you can define entirely new top-level constructs: he defines an exercise which has a solution and will be a part of a solution list. The semantic linking part is that other parts of the document will refer back to these solutions. Some output formats will have all solutions inline, with the exercises, while other output formats will collect all solutions in one place at the end. HTML is not flexible in that manner.
What is extensible is XML. It's entirely feasible for XML to be the input, but for better-or-worse, most people are even more turned off by XML than they are by something like rST.
Yep!
> 1. HTML is designed for representing webpages, not books. Your intermediate representation will become HTML's DOM, which is likely not well suited to the book use case. You'll either need to use an existing HTML-to-DOM parser or build your own. One big limitation of the DOM, as I see it, is that it doesn't have the concept of a page number.
I guess my point is that while the main use of HTML indeed to render webpage, it seems pretty well suited at rendering most if not all types of documents. The page number issue you mention is typically only part of the presentation and is handled by the CSS paged media module (though admittedly, support of this isn't universal in my experience).
> 2. HTML is not extensible in the way the author talks about. [...]
Except it is! This is what HTML Custom Elements are all about. Combined with CSS, it can handled to different rendering formats you mention pretty well.
> What is extensible is XML. It's entirely feasible for XML to be the input [...]
I'd actually argue that raw XML is the wrong approach for most things, as the goal of XML is to be extended (e.g.: SVG, MathML, SAML, etc.). But I feel like that's a whole other discussion.
Anyways, I think this is a good conversation and wouldn't mind continuing over email (see my profile). It's fine if some people like rST, but HTML seems better suited for these use case than people make it out to be.
I think that bringing in CSS is a bridge too far for the case of writing a book. Authors are no longer just writing HTML, they're writing HTML and CSS. And CSS is intimately tied to actual web browsers - you're now going to need a browser display engine to be an integral part of how you render your book. (Or you're going to need to implement just enough of that yourself, which is a big undertaking.)
The point of comparison is Markdown, which is relatively straight-forward and simple. HTML and CSS is not that.
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.
Two problems I had were: (1) common with a lot of systems, the RST tools don't contain an RST unparser. I really wanted to be able to generate RST files automatically by merging content from other RST files and other sources and working with them via a document API. The RST tools don't support that. (2) The RST tools expect a certain defined set of blocks for a particular document; it would be very possible for a system to represent blocks in a generic way which would make possible tools that can transform documents without necessarily knowing the definitions of blocks inside it.
These are problems w/ the tools, not problems with RST itself but every time I'm forced to strip my code back to the walls is an opportunity to think about some other markup system such as something HTML-based.
Instead of HTML you can use XML to write structured documents. With XML you can define whatever custom tags you need with schema validation if desired. The advantage of this approach is you have full control over the input schema and output, but the downside is XML is much more syntactically noisy compared to Markdown or RST and you will need a script to parse & convert the XML to your preferred output format(s).
XSLT will happily output any number of formats from an XML doc. There's also a number of existing and very capable XML schemas for documentation like DocBook. You can even go from a lightweight markup like RST or Markdown to DocBook and then have an XSLT pipeline that delivers that intermediary to any number of formats. There's also very capable graphical editors that will spit out DocBook directly.
I find the aversion to XML very strange. It was definitely applied in some places poorly by products with "Enterprise" somewhere in the name but the language itself is very useful. The aversion to XML has led to a lot of work re-learning of the lessons that led to some XML features. It's also led to implementing XML features poorly in other languages.
Loads of other systems I work with still output XML, and I have fast, powerful tools to work with them pre-installed on any Mac I work on, and it doesn't even matter that Apple hasn't updated them in a while since XML hasn't really been changed either. I can look at an XML doc and have so much information about the data inside just telegraphed into my head, just by the way the things are shaped. I don't have to read the tags like a book, I can just gloss over them and still get enough to understand the strings/numbers inside. Yet, they're still on the page, out of focus, in my periphery, providing anchoring and structure and navigation, I can find my place. Maybe I'm just a freak, or that comes from 20 years of staring at them. Whatever reason, I just can't do that with JSON as easily or as fast.
I don't hate on any of the other formats (save for YAML, not interested), and I really appreciate JSON's brevity sometimes for simple data and small responses, but that brevity quickly turns into wisps of formatting and text seemingly floating out in the middle of nowhere.
Same. Every back end project I work on I recommend XML as the transport and every time I get a reflexive "ugh, XML". Then I spend an inordinate amount of time making Swagger endpoints so a consumer can figure out how the JSON output is supposed to behave.
It really isn't. Both namespaces and schema cause far more problems than they solve. And the theoretical advantages of having a declarative language for expressing transformations (and schema) is outweighed by how awful it actually is to write XSLT (and schema).
If we had namespaces for classes and id's in CSS we'd be able to transclude content from one HTML to another HTML page easily but we don't so we can't. (Shadow DOM helps a bit though) The "hygenic macro problem" is one of the many barriers people face doing metaprogramming. In the RDF world it's refreshing to be able to import facts from multiple systems into multiple namespaces so you can put data you got from different sources into the same database and "it just works".
I don't think namespaces solve the macro hygiene problem, because if you're going to have macros then they need to be able to interact with and manipulate your namespaces, and sooner or later you need your macro to e.g. generate a fresh identifier for use within an existing namespace and then you're right back where you started.
Being able to disambiguate when you have one document including another would be useful. But the cost/benefit on XML-style big namespacing up-front just doesn't stack up.
- 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.
(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.)
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.
In python, rST is just one of many supported input formats for docutils: https://docutils.sourceforge.io/README.html#purpose
The entire point docutils is to parse formats and convert using an API: https://www.docutils.org/docs/index.html#api-reference-mater...
If it had that it would be a 200 foot tall giant robot, as it is it's just another documentation generator.
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.
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.
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.
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.
They also have some nice instructions on automated deployments.
https://github.com/rust-lang/mdBook
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.
This example shows a fairly short GitHub action to deploy to GitHub pages: https://github.com/rust-lang/mdBook/wiki/Automated-Deploymen...
Speaking as one who actually produces blogs on rare occasions, I have to say starting every post with "This is just my experience and may not apply to you this is not a claim of global applicability this is just applicable to this circumstance you're the one who chose to read this I didn't force you" and so on isn't exactly the most compelling way to open a post.
Though I have to admit now I'm really tempted to add that into my post template in like 2pt font or something, just so when people on HN complain I can point them at it.
By contrast, I was careful to criticize the title as clickbait, not the post, which is useful (or the book, which sounds genuinely interesting). I wasn't perturbed by the title. By your comments, sure, but that's your doing, not Hillel's.
"Why I prefer rST to Markdown"
or
"Why I prefer rST to Markdown for Typesetting"
Since it's a clearer statement of the author's meaning, and since very few users interested in Markdown are going to be doing any typesetting, it seems like a more meaningful title to me.
But less likely to draw in readers... to "bait" them, if you will.
They've got extremely similar goals, and for the most basic text, both read and write like plain text too. And it was obviously a time when this thing simply became a thing everybody desired, so many "formats" appeared.
Why did MD win has — IMO — nothing to do with how it's "simpler" or "more readable" — they are largely interchangeable for anything that's easily represented with whitespaces in pure ASCII.
Or does someone claim that the following is unreadable gibberish that they need a parser for?
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.reST offers a lot of additional formatting features which are beneficial if you need them and cruft when you don't.
I first started using Github-flavored Markdown after signing up for Github in 2010 (possibly earlier under another alias.) I used reStructuredText for Python docs a couple times. I found the latter to have a much higher learning curve and I haven't had a reason to use it since.
But looking through examples at https://docutils.sourceforge.io/docs/user/rst/quickref.html#..., I really see a lot of non-simple stuff done in an obvious way too (block quotes, tables, bullet and enumerated lists, sections and headings, separator lines...).
By the time you got on the markdown train, it has already won out, and you've probably seen a lot more of it than of reST, even if MD still wasn't standardized. As a counter-point, having done lots of reST with Python docutils prior to 2010, I still mix up reST and MD — there's nothing intuitive about any of their special syntax, and our perception is mostly tainted with our prior experience. I've also written a lot of ASCII-only docs prior to either of those, and most people used ever-so-slightly different conventions there as well (somebody mentioned using /this/ for italics as well).
reST was standardized in the form of a Python PEP from its inception so you could at least rely on learning it once.
Edit: My ultimate point is that you (and most everybody else, including me) are using MD because it's more popular, not because it's "better".
I agree that reST is probably a better fit for complex use cases like building a docs site. But it's overkill for Facebook Messenger or even forum posts, IMO.
If you want to use a mark-up language in a chat app, a subset of either would serve you just fine and both are equally simple. It sounds like you are comparing a subset of what-is-markdown-today (and there are still variants) to full reST, which I don't think is a fair comparison.
From a very brief look, here's some things that probably aren't generally necessary (and aren't included in Markdown): Document structure, Bibliographic fields, complex footnotes and citations, directives, substitution definitions
All of these increase the number of things I have to escape, as well as my cognitive load when writing documents. And that's before we talk about reST config settings!
You could use a subset of reST, or you could just use Markdown!
Unreadable? No. Frustrating to type out? Yes. Underline style is annoying when editing, and even if you technically don't have to match the length you will still feel obliged do. Double backtick is just awful to write, annoying out of all proportion to how much extra time it actually takes.
I still wouldn't go as far to say the MD or RST syntax is hard in any way (and really, asterisk which requires a Shift key is worse than double backticks).
We had our documentation in asciidoc and it was awesome to write. We migrated to RTD/Sphinx/rST mainly for 1) better handling of i18n and 2) better handling of multiple-version-documentation (switching between versions)... and I loath rST every day. It's syntax is just abysmally awful and the tooling sucks (seriously, it's not just bad... it sucks!).
Nowadays there is antora but still - i18n is still a problem…
And markdown - as a simple tool to add some simple and basic formatting is just awesome and it's easily readable even if you don't have parser and end up having to read plaintext…
Asciidoc just seems to be much higher quality in general.
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.
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.
:table-caption!: :toc: macro :sectlinks:
toc::[]
But at the same time, I find the writing experience for more advanced stuff too poor. The author talks about references, but do we have a language server that can look up available references, headlines, figure names etc and help you auto complete?
That’s what would make me take the plunge to a more advanced system.
That would be a total gamechanger! Having the ability to do ref/doc links and not have to worry about stale topic headers is another thing I loved about writing in rST that I miss now that I'm back in markdown.
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).
I'm reminded of all of the alternate worlds that didn't quite come to fruition, but could have (Lisp, Smalltalk, BeOS, etc.).
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.
That doesn't mean we stopped doing it.
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.
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.
https://djot.net/
Designed by one of the authors of CommonMark, an attempt to specify a standardized flavor of Markdown.
EDIT: By the way, recent comment from the primary developer: https://github.com/jgm/djot/discussions/310#discussioncommen...
Then again, it is already in pandoc, so I suppose you can trivially move out of it.
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.
https://github.com/rstcheck/rstcheck
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.
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.
> I think Restructured Text is better for writing books than Markdown.
That would be a better title.
I'm not using a language simply because it was aiming at something better, if it missed the mark.
If you really want you can define bold italic text using some styling magic, but that's quite awkward.
How do you write <i><b>x</b>y</i> in Markdown (without using HTML tags)?
I hugely prefer to write in RST, but as soon as I'm not alone we always switch to MD, given enough coworkers.
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.
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.
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
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.
I assure you my mistake was not because of good-intent towards Media[Ww]iki.
RIP
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...
1. https://docs.racket-lang.org/scribble/
2. https://docs.racket-lang.org/pollen/
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
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.
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.
> 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).
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?
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)
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.
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.
You can also reorganize things and keep old links as 302s.
At a minimum, you should be aware of when you're breaking links and it should be a conscious decision.
I write a lot of markdown at work, and while you can't do this in commonmark, most parsers will absolutely let you define custom block types and transform the doctree and other things. You know how three backticks followed by the word 'python' produces syntax-highlighted code almost everywhere? You bet that I can do `::: warning` in my documentation to make the following content appear in a big red box with an exclamation mark.
As long as you don't put raw HTML in your source, you can even render to different targets like PDF. jupyter-book is a good example here.
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
rst:
scroll: "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!
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:
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!
[1]: https://pages.micahrl.com/progfiguration/
What makes so many designers of these plain text formatting languages choose to not preserve newlines? I don't get it. Preserving newlines is one of the main features of plain text.
This causes the same annoying thing as hacker news comments do, like this intended multiline shopping list:
-eggs -flour -milk -sugar -salt
The iirc, syntax is :inline{property} and
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.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?
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.
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
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.https://pandoc.org/
Or “how I stopped caring about doc formats”
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.)
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:
The result of running that tool is always API documentation, so you might need something for docs that aren’t structured that way.
Now, granted, I am clearly ok with fenced sections. And I love org-mode for most all things.
That's very annoying to write, and some people even add overlining. We're entering the ascii art domain here and I don't have time for that.
Markdown has already won over the technical users.
Enjoy your infinite support tickets caused by markdown. RST does nothing to help this.
Of course Markdown is simpler in many aspects. But therefore it lacks many things that rST has.
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.
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.
Is this what the author means by markdown being lightweight, since the inverse isn't true except trivially?
But I'm so sad that asciidoc isn't supported by pandoc.
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.
I assume they’re talking about s-expressions? Then that’s a really bad example, because those are objectively beautiful.
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
I wish there was a way to use it to render HTML and not just PDF.
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.
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.
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.
So, while I understand all the good parts, I am still kinda not convinced it's a better option looking at the final product.
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.
Shiny tools are nice when it’s only you and you don’t need to keep the results forever.
MS Word supports version control, but patches are a terrible idea for documents. Again, the whole point of a document is to make it easy to read, so the formatting becomes a huge pain in the ass for a patch. Patches are designed for lines of code, not the formatting, layout and content of rich text documents. Trying to force documentation to work like code is making the computer happy, rather than the computer making people happy. It's the opposite of what technology is supposed to be for. Think about what you're spending your life on. You gonna look back when you're 80 and think, gosh, I'm so glad I spent those extra hours going back and forth with a dozen people on the internet to try to approve an update to documentation? I'm so glad I spent an extra hour tweaking this program code so that this document would have an embedded table aligned right? I'm so glad I had to write a separate program to be able to format this Markdown Table so that I could actually edit and save it so that it renders?
Docs should be living / not require requests for patching. Humans should be entrusted to just update a document immediately, with a log and comments to allow reverting entries only if necessary. Aka a wiki (and a WYSIWYG one at that). The whole purpose of patch requests is not to gatekeep information, it's to make sure a change doesn't blow up a program. Documentation isn't a program, just change the document.
Never before on an article I've felt the vibes of the "I stopped reading there"-meme harder than here.
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.
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.
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.