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