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).
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.
> it’s fantastic for chat applications
Slack is the absolute worst at it; I am unable to at all figure out what its "parser" (which feels like cobbled together regexes … but even then … not?) is doing.
[link text](URL)
Worse to me is that Slack considers "we mutated the input you typed, and then proceeded to misrender it" as "Won't Fix/Working As Intended". (I reported it a while ago, that was the resolution.)
Want to italicize some text? Easy right, just do it like *this*.. nope that will bake it BOLD, gotta write it like _this_ for italics.
https://support.google.com/chat/answer/7649118
The only thing I like is that you can colorize text, but there's no syntax for it, you gotta highlight it then choose a color in the formatting toolbar.
It's annoying to no end when you memorized the syntax and Google decides to not even follow it.
*bold*
/italics/
_underline_
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?
Perhaps //italic text// would be acceptable.
If people want to make foo or foo bar italic, they write /foo/ and /foo bar/.
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”.
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!
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.
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!
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.
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).
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.
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...
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.
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 just wish the typst compiler had a way to output html. It would be perfect for making online documentation and blog posts.
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 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.
Do you really read Markdown in plain text editors? I only do occasionally. 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.
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
#let important(body) = {
text(red, body)
}
But whatever you do, #important[Dont *panic*!]
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.
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.
* 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/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...
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.
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.
>...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.
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
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.)
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
> ..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.
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.
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.
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.
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.