top | item 41254936

Markdown is meant to be shown (2021)

204 points| SoKamil | 1 year ago |daringfireball.net

165 comments

order
[+] voidhorse|1 year ago|reply
I think the bigger problem is that apps that don't need/shouldn't use markdown reach for it as a default and build upon it when they would have been served better investing in richer markup.

Take ulysses (mentioned in the article) for example. It has grown into a full-fledged writing and word processing application, but its being based on markdown originally has only hampered that. They've had to implement all of these clunky extensions and features in terms of markdown, and as the post states, try to hide the fact that it's all markdown to make it feel more like a classic word processor. At this point it just makes the whole experience clunky. People that just want to write markdown deal with weird extensions and frustrating syntax hiding, people that don't need to learn some minimal markdown just to use a word processor...

It's 2024. I hope companies start to realize that markdown is a fantastic solution for certain cases but it is not the only solution. Some applications really are better served by more complex, but much more expressive markup languages, especially if they are going to shield the user from it all anyways.

[+] sbuttgereit|1 year ago|reply
Couldn't agree more.

I find that I'll choose Markdown (assuming it's a choice) when I expect multi-modal consumption... where a given text will in some contexts simply be presented as-is using plain text and the text can also take advantage of rendering into a more styled presentation.

I write in-database comments (e.g. PostgreSQL's `COMMENT ON [...]`) using Markdown for this reason. My go-to database documentation tool of choice (https://schemaspy.org) will very nicely render the Markdown into styled documentation integrated into the rest of the documentation it generates, but the plain text rendering when I'm looking at those same comments via `psql`, where no Markdown rendering is applied, still look decent due to how Markdown works.

[+] j1elo|1 year ago|reply
Ulysses? Take an app with a MUCH wider audience: WhatsApp!

They use Markdown-esque syntax for message formatting. It mostly is Markdown, with a single caveat that gets me a lot: *Single asterisks* become bold, instead of italic. For italics, you have to use _underscores_.

Other syntax works fine. Slack also uses Markdown. In summary that's nice as it is just one single syntax to remember across systems. I wouldn't enjoy too much that every app started having its own different, more expressive syntax, at least not for apps which their primary job is communication, not text edition.

[+] jasonpbecker|1 year ago|reply
Of course you can use any number of ways to implement rich text or formatting. A lot of people want Markdown because of the portability of plain text. Markdown has served as a good mechanism for plain text formats that still can do a bit more. Ulysses would lose a significant portion of its audience if it moved to it's own syntax or some form of rich text or its own binary. A new audience would likely become interested-- though fighting Microsoft Word is ... hard to say the least.

Maybe that's where Ulysses wants to go, and its own implementation of some non-standard elements suggests that. But I also know people who will not use Ulysses because of its non-standard Markdown elements resulting in files that are less portable.

[+] j1elo|1 year ago|reply
Before I learned the existence of Markdown, the intuitive most logical markup for me was (and after 10+ years of writing Markdown, still is):

* *Asterisks* should be bold. Like WhatsApp and Slack do. Because they bring attention to the eye, marking a strong emphasis, and also because for italics there seem to be a much better alternative.

* /Slash/ should be italics. Young me thought this was so obvious! Because italic text is leaning to the right, just like the slash bar. (Note that with time I ended up realizing that this would be a bad idea because slashes are too commonly used in plain written language. The parser would need to be too clever. But still, seemed nice for a while :-)

* _Underscore_ should be underline. I mean, the name says it all. This is so obvious to me that I never understood how it's not the case. I had been writing _this_ to visualize an underlined word for so much time before learning Markdown, that having it for italics just feels strange.

Anyway. If someone knows some resource about the thought process, discussions, or decisions that were made to adopt the current syntax (especially to decide that _underscore_ should italicize, which feels so strange) please let me know, I love reading about that kind of thing :)

[+] spc476|1 year ago|reply
Back when most writers used typewriters, the convention was to use the underscore to mark text that was to be italicized. And because they were using typewriters, they would backspace to the first letter of a word or phrase, then type the underscore under each characters to be italicized. When computers came along, backspace worked differently (back up, replace character with space), so the convention was to start and end the word/phrase with an underscore, _like this_.

Using asterisks for bold is again an adaptation for computers. With typewriters, you could just back up and retype the word/phrase to get a bolder look (maybe a few times to really make it stand out).

[+] setopt|1 year ago|reply
The main problem with slash as italics is that I very often write either file Unix file paths (like /etc/) or lists of alternatives (like vim/emacs/etc), and such markup languages tend to get confused.

I rarely have that issue with * and _, since they only really appear as explicit symbols in code or math which already have other syntax markers.

[+] BalinKing|1 year ago|reply
This is precisely how Org mode works in Emacs, IIRC. Now I'm curious who was the first person to invent this syntax—like you say, it seems like a very natural choice, so I'd be surprised if it doesn't have a long history of some sort.
[+] samstave|1 year ago|reply
This is how it was in yee olden times... I've asked a couple time that HN takeone the content boxes of reddit's markdown. What I do with markdown (copying formatting of tables and such super well, is to paste it into the 'Visual Tab' in Rstudio, and then click to the CODE tab and copy the properly formatted markdown, then past that into a reddit comment and get the great formatting that I want.

For example when I have GPTs spit out tables for researching a topic.

https://i.imgur.com/4gIGYLu.png

https://i.imgur.com/DJVhrUr.png

https://i.imgur.com/aTRWN5S.png

[+] nj5rq|1 year ago|reply
As someone else mentioned, this is how Org mode works on Emacs, not only that, but by setting:

    (setq org-hide-emphasis-markers t)
You can hide the markers (*, /, _, etc.) by default, and toggle them with:

    M-x visible-mode
It also has many other features that integrate well with Emacs.
[+] tasuki|1 year ago|reply
In polite society, underlined text is not a thing.

I'm with you wrt slash for italics, but sometimes you also just want to write a slash... how would you do that? Underscores are good because you never really want to display them...

[+] gkoberger|1 year ago|reply
One thing I love about being able to see the syntax when editing is that you know what's about to happen. A backspace will always delete the previous key; you won't end up in a situation where you're deleting a whole block of content. And when you type, you know if the cursor is on the left or right side of the "*", whereas in WYSIWYG it could be on either side of the invisible change from bold to regular.

It's much more relaxing for me to write in Markdown, because I don't have to think about the mode I'm in or how to get out of a small pickle. Everything is just a character.

I don't think Markdown is for everything. Microsoft Word is not a Markdown editor, and most people are better served by a WYSIWYG editor. But for writing content, I always prefer personally to write in markdown (and to see the syntax), since it's easier to focus more on writing and less on the editor.

[+] svachalek|1 year ago|reply
The thing where backspace magically reformats half your document is so frustrating. I wonder if Word's solved it as it's been decades since I've used that, but it seems like pretty much anything else I use still has that issue.
[+] yencabulator|1 year ago|reply
This is giving me strong WordPerfect 5.1 Reveal Codes vibes.
[+] ximm|1 year ago|reply
You haven't dealt with bidirectional text yet, have you?
[+] fenomas|1 year ago|reply
Related: given that markdown is meant to be read, it kind of drives me up the wall that some people nowadays run autoformatters like Prettier on it. Super-aggressive formatters like prettier remove various whitespace, and mangle other things that human authors do for readability. Which is fine if the file is something that's only ever meant to be parsed by scripts, but the whole point of markdown is that people read it!

(edited to add: It wouldn't really be an issue if prettier had some config options for not mangling whitespace, but that ship seems to have sailed for some reason.)

[+] diwank|1 year ago|reply
Yes! I sometimes prefer to use `====` h1s and `----` h2s especially when I am writing slides or taking notes on a live call for others and I hate that prettier and other linters would automatically turn them into `# ` and `## ` ...

Please stop doing that, prettier.

[+] bastawhiz|1 year ago|reply
> Which is fine if the file is something that's only ever meant to be parsed by scripts, but the whole point of markdown is that people read it!

Nobody is running prettier on their code or markup for the benefit of the computer. If it's not readable, it's just a bad formatting tool (or wasn't configured properly). The whole point of a formatter is to make it easier to read.

[+] danbee|1 year ago|reply
I'm not a fan of Prettier at all. A log of the time I find it makes code uglier.
[+] The_Colonel|1 year ago|reply
Well, Markdown is a superset of HTML where extra whitespace is usually collapsed, so this behavior isn't surprising. Having "source" Markdown looking meaningfully different from the rendered Markdown seems like an anti-pattern.
[+] msf1024|1 year ago|reply
The reason I write in markdown is because it is fast and keyboard-driven. I don't want to see it when I'm looking at my notes or editing them. The idea that it is meant to be seen is no more than a personal preference.
[+] Slackwise|1 year ago|reply
> because it is fast and keyboard-driven

How is it faster to press `*` than `Ctrl-I` in any other rich text editor?

> The idea that it is meant to be seen is no more than a personal preference.

Actually, the entire philosophy of Markdown is that, even if you didn't process it into HTML or some form of rich text, it uses common conventions that have been used across Usenet, IRC, and plaintext files for years, and is thus readable without ever being processed. In fact, you can likely take various plaintext files and process them and they'll gain many incidental markups and highlights.

Meaning, Markdown is Markdown without needing to be turned into HTML or rich text. It is, in itself, a great way to universally markup text as people have been doing online for years.

[+] Joker_vD|1 year ago|reply
But uh, how do you undo the styling from the keyboard? Does Backspace turn "italic" into "*italic"?
[+] thomascgalvin|1 year ago|reply
I generally don't even like syntax highlighting for Markdown. I find having the text jump around because it became bold or italicized distracting, and it's even worse when a header is suddenly a larger size and everything below it is pushed down the screen.

Markdown is simple, and I like working with it simply.

I suppose there is some value in having the more complicated aspects, like images and tables, checked for syntax so you can see if you've made a mistake, but I run a macro to generate those anyway, so I'm fairly confident in the result.

[+] diwank|1 year ago|reply
Yep but to me this feels like a lot of poor ux decisions too. I would def appreciate the visual indicators of italics and bold text but ffsake please dont toggle it every time I add a bloody keystroke. It's so jarring when editors do that. There are so many alternative designs where you can have both. For instance, on my vim the highlights only get added/removed when I switch back to normal mode, during editing nothing changes except for the actual keystrokes.
[+] red_admiral|1 year ago|reply
Trello, once made for developers by developers, has announced that some time this August they will disable the markdown editor on desktop and force you to use the WYSIWYG one. The markdown one will remain on mobile, so there's clearly no compelling reason to do this. There won't even be an opt-out anymore.

(Could someone please find out which resources we all have to add to ublock to work around this?)

[+] taeric|1 year ago|reply
Oh wow. From headline, I first thought this meant that viewing a markdown document should show me the markup. Which falls on its face with images and links, of course.

No, this is about editing the document. And... I confess I'm confused on why folks would want the opposite? WYSIWYG is, of course, a thing and popular for many reasons. So, I can see having the option to operate in that way. But a huge benefit of markup languages of any kind is that I can see the markup. Fully agreed that I should be able to see it.

[+] thinkling|1 year ago|reply
I use markdown for note-taking. I do as much reading as editing, and they're generally intertwined. I don't want to switch between "view mode" and "edit mode". I want to be able to embed links but not have the document become cluttered with long, ugly URLs. I want to use headlines and bulleted lists and have them auto-formatted. I also want to keep my notes in a 100% portable human-readable format. (No MS Word, no Bear, no Evernote, etc.)

For my use, the best solution is an app that shows me the formatted (styled) output, until I navigate the insertion point into it, and then expands the text to show the formatting.

Obsidian is an app that does this. I don't love other parts of it, but the editing experience works well.

(What I really want is the search/browse experience of nvUltra with the editing experience and cross-platform presence of Obsidian.)

[+] Doctor_Fegg|1 year ago|reply
> I have no idea why there are now apps that use Markdown as their back end storage format but only show styled text without the Markdown source code visible.

Because backend storage of rich text is not a solved problem?

RTF is a horrid, over-complex serialisation. Some platforms have their own internal format for rich text (e.g. NSAttributedString) but serialisation is either lacking or platform-specific.

Writing as WYSIWYG but storing in the backend as Markdown is not an insane idea, and I say that as someone whose muscle memory has been cmd-B/cmd-I since 1992 and would never choose to actually compose in Markdown unless I had to.

[+] tjoff|1 year ago|reply
Though only show the markdown if one is expected to edit it (which would be the case in an editor).

Otherwise, if the usecase is consumption you are better to show the generated output.

[+] jessriedel|1 year ago|reply
Yes, the blog post could have made it clearer that the author was talking about editing mode only. (His wording was “meant to be visible to the writer”.)

The issue, of course, is when the writer is also the reader, such as for the note-taking apps. It’s not always clear then what mode the user wants to be in.

I’m pretty happy with the compromise struck by Bear, which does some of what the author is complaining about. Bear’s technique is to show the formatting (i.e., hide the markdown syntax) for everything except the “word” (contiguous non-white-space) that you are currently editing, as determined by the location of your cursor. This lets you edit the markdown directly, ASCII-character-by-ASCII-character, but the rest of the doc looks pretty. It’s not perfect, but hiccups are rare and I find it vastly better than the alternatives: (1) a conventional WYSIWYG editor or (2) a hard distinction between writing and reading mode that the user needs to constantly toggle actively as they use their notes. But it seems fine to me that different users prefer any of these options.

[+] filcuk|1 year ago|reply
Yeah, I'm happy I can edit via markdown and fallback on it if the site is down, for example, but I see no benefit to intentionally making it less readable when reading/presenting.
[+] bfung|1 year ago|reply
> Maybe I don’t know much about Markdown…

Says the inventor of it, 20yrs ago. https://daringfireball.net/projects/markdown/

[+] hungie|1 year ago|reply
Inventing a thing and understanding a thing aren't necessarily the same. We adopt technologies and make them our own, sometimes away from the inventor's initial vision.

I think if people, by and large, enjoy markdown one way (for example in this forum, where you italicize text but the control characters don't show), then maybe the inventor is wrong. Or is right about their preferences but shouldn't try to make their preferences the de facto standard.

[+] ericyd|1 year ago|reply
> Trust me, it’s meant to be shown.

Maybe it's time to accept that this thing you created is bigger than yourself and it's future is not in your hands.

[+] gsinclair|1 year ago|reply
Grover thinks the purpose of Markdown is that the author knows what HTML tags will be generated. That was his purpose, but it’s long outgrown that!
[+] iambateman|1 year ago|reply
Ahh, yes. I, as a developer, think Markdown is wonderful – simple even – so I use it all the time. It finds it's way into my applications and interfaces. The pure elegance is the stuff of dreams.

Then I bring a client into their app for an onboarding meeting. When they see a bit of Markdown, they start to fidget, then sweat. "Will I be asked to perform these magic incantations?" they wonder. They feel a bit of queasiness but try to hold it back. Perhaps this will be ok. But, after about 10 minutes, I show them that `# Header` is how you make a header.

Their disdain is now total...How dare I imply that a hashtag implies a header. This is hard.

Then, I show them a link. "It's just like this", I say: `(https://example.com)[example link]`. "You'll get used to it."

Finally, the client pounds his fists on the table. "That's CODING DAMMIT. WE PAID YOU TO DO THE CODING YOU *$$HOLE. I want it to be like...well...Microsoft Word."

---

You see, my friends...the real problem here is that Microsoft Word is a nightmare but it is _the_ nightmare to which all other dreams are compared. And thus, sheepishly, I awaken, and install TinyMCE.

[+] haroldp|1 year ago|reply
And now you have a new job: untangling garbage <a><em><em style="font-weight: bold;"><em><span>HTML&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</em></span></a></em></em> disasters and coaching your clients about keeping the text styles in alignment with the site branding. :)
[+] kragen|1 year ago|reply
this sounds like fiction you wrote about stereotypes rather than honest reporting of your experiences—and not only because you got the markdown link syntax backwards
[+] rubymamis|1 year ago|reply
> I have no idea why there are now apps that use Markdown as their back end storage format but only show styled text without the Markdown source code visible.

The reason why we do in Plume[1] is simple - we want a WYSIWYG editor for our non-technical users, yet also the reassuring longevity of a plain text format such as Markdown. Simple as that. In my opinion, it's a combo that's hard to beat.

[1] https://www.get-plume.com/

[+] ides_dev|1 year ago|reply
This is precisely why I use Bear [0] (although Bear does hide the link URLs) and just cannot get on with Notion. The worse thing about editing in Notion (and other editors where the syntax is hidden) is trying to adjust `mono-space text`. It always seems to get confused about whether I'm inside the mono-space area or outside it and I end up making stuff mono-space that shouldn't be or vice versa.

[0] https://bear.app/

[+] teo_zero|1 year ago|reply
When I edit a C program, comments are highlighted in a specific way, but the // characters are not removed. Why should editing a markdown text be different?
[+] bastawhiz|1 year ago|reply
If you only care to expose limited formatting to the user, whether the file is stored in Markdown or not is immaterial. It could be stored in Word 2003 DOC format and export to Markdown, and if the serialization and deserialization are faithful, it doesn't matter at all.

Markdown is portable, fast, safe, and simple. Being able to dump your data as Markdown (which you know works, because the Markdown version is the literal source of truth) means you're guaranteed to be able to extract your data and move it wherever you want with perfect fidelity. That's a huge bonus.

The argument here is pointless if your concern isn't the syntax: Markdown _as a serialization format_ versus Markdown _as a typeable syntax_ are two separate concerns. The UX of a tool meant for editing Markdown is going to be extremely different than a tool to edit simple rich text.

In my own app, I default to WYSIWYG with an option to edit the raw markdown (for podcast show notes, which have very limited formatting options). Why? Because the alternative is HTML and that sucks to write by hand (especially if you can't use most tags).

[+] Vaslo|1 year ago|reply
I’ve run into this exact same issue with many of the self hosted wikis/tools. Some of the ones I had interest in like Trilium don’t have native support and you have to use a plug-in hack to see both the code and the preview, or you have to click back and forth between rendering and redoing.

I just wouldn’t have markdown in my software if I wasn’t going to support a preview.

[+] Y-bar|1 year ago|reply
I am currently trying to fit Obsidian into my workflow as a note taking app, and this is one of my main gripes about the app. Another being that it does not integrate well with the operating system spell checking, so adding a word elsewhere to the system dictionary does not reflect in Obsidian, and the other way around.
[+] bachmeier|1 year ago|reply
Obsidian has both live preview and source mode. I have a shortcut to switch between the two. I use live preview when making lists and source mode for most other documents.