Hacker News Reader

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

Markdown is the Unix of rich text formats.

Ready for Markdown wars?

You mean like original recipe vs. GitHub flavor vs. Reddit flavor vs. CommonMark? We're already there, dude.

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.

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

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.

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.

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

Google Chat is also somewhat terrible at it.

Want to italicize some text? Easy right, just do it like *this*.. nope that will bake it BOLD, gotta write it like _this_ for italics.

https://support.google.com/chat/answer/7649118

The only thing I like is that you can colorize text, but there's no syntax for it, you gotta highlight it then choose a color in the formatting toolbar.

It's annoying to no end when you memorized the syntax and Google decides to not even follow it.

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.

And even HTML was not safe because and were too easy so now we have and because somehow those are more meaningful.

The worst part of the to migration is now 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 tags, not .

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

I agree with you on that.

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

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

True.

Perhaps //italic text// would be acceptable.

// is common in URIs.

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

I have no regrets on this one. I thought people would use both, and people do use both.

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.

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.

That sounds horrible. You should never mess with the semantics of standard shortcuts like that. Please let paste mean paste and not "smart" paste.

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.

Interestingly it annoys me when other tooling *doesn’t* do this

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.

>having it in the raw form while typing

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

Aw that’s embarrassing. Thanks.

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

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

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.

Yes!

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

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

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

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.

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

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.

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.

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?

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

> In fact, 90% of what I wrote before I knew markdown was valid and decently formatted markdown already.

Bingo!

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

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.

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.

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

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

Even if you've never seen markdown before, it's pretty obvious.

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

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

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

You know what it is, but you have no idea what it looks like. Maybe it is a garbage picture that doesn't really add anything. Or maybe the picture is a necessity to understand the architecture of the system. Someone put the time and effort to create that picture, you'd imagine for a reason. Maybe worth having a look?

Maybe, just maybe, looking at that image is a good idea to do before reading 20 pages of documentation? Probably a good idea to look at even if you only intended to glance at the documentation for 20s.

Because that's what markdown mostly is in my experience, documentation. And the images, if they exist, often are a very important part of that.

Now some images are garbage, but you don't know because the alt-text will not be "Superfluous image that doesn't add to the understanding". Maybe it depends on the reader, is the reader fluent in design patterns (and crucially, is the project following the design pattern as is or have they made their custom modifications to it?).

But in reality it will likely be a flowchart. Kind if an important piece that really help when reading the text. Or maybe just an image of a header and all the field sizes. Can you do it without it? Sure. But remember that not all documentation is perfect, it might not have had someone pouring his/her heart in it. It might have been rushed. So as often is the case you actually do need both the image and the text, not just to help understanding (which alone really is reason to make sure you look at both) - but because you need both to get all the information.

I sigh when I see a .md. Especially in documentation, because in reality that probably means that I have to either get the dependencies and look up the build process to build it myself. Or I have to go to the official project web page and browse the documentation there.

If it is a .txt or .pdf I know what I'm in for, and I know I have the tools needed to view it.

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.

Markdown can't display images at all, either... Which is my point.

(you know you can write paths in a .txt file too?)

But you would have to invent or assume a format for that .txt, and markdown is easily rendered if needed

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.

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

I think a good example is all of the wonderful documentation that's been created with mdBook.

Heck, the Rust book was written with it, and they also made a print edition, so maybe markdown is enough even for that.

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

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.

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

Both public and tailor-made: https://github.com/rust-lang/book/tree/main/tools

Awesome! You and Carol rock!

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

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!

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!

The link below (https://github.com/rust-lang/book/tree/main/tools) could imply the book was written as Word .docx with named styles, which enabled transformation into markdown for the mdBook?

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

MDN documentation is written in markdown. I’ve always felt this was a resounding endorsement of markdown over other more “powerful” markup languages because if they can do it, why can’t you? (not you in particular, but anyone who thinks markdown is inadequate for docs)

https://developer.mozilla.org/en-US/docs/MDN/Writing_guideli...

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.

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.

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.

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