Markdown Is Meant to Be Shown: Stop Hiding the Syntax (2021)
Jason Snell critiques Markdown editors on the App Store, advocating for visible syntax and clear distinctions between WYSIWYG and Markdown editing, praising "Hey World" for its effective approach.
Read original articleJason Snell discusses the varying quality of Markdown editors available on the App Store, emphasizing that not all implementations meet user expectations. He argues that a good Markdown editor should display every keystroke, including hyperlinks, rather than hiding them. Snell appreciates syntax coloring and styling that enhances readability without obscuring the underlying Markdown syntax. He believes the essence of Markdown is to allow writers to see the punctuation characters that correspond to HTML tags, ensuring they know what the final output will look like. Snell expresses confusion over apps that use Markdown for storage but only display styled text, advocating for a clear distinction between WYSIWYG editing and Markdown editing. He cites "Hey World" as an example of an app that successfully balances these elements by allowing users to edit links in a popup while maintaining visible Markdown syntax.
- Jason Snell critiques the quality of Markdown editors on the App Store.
- He insists that Markdown syntax should always be visible to users.
- Syntax coloring and styling are appreciated but should not hide the Markdown code.
- Snell prefers traditional Markdown editing without hidden formatting.
- He highlights "Hey World" as a successful example of effective Markdown editing.
Related
My weekend project turned into a 3 years journey
Anthony's note-taking app journey spans 3 years, evolving from a secure Markdown tool to a complex Electron/React project with code execution capabilities. Facing challenges in store publishing, he prioritizes user feedback and simplicity, opting for a custom online deployment solution.
The Eternal Truth of Markdown
Markdown, a simplified code alternative to HTML, enables diverse document formats from plain text. Despite lacking standardization, it thrives for its adaptability and simplicity, appealing to writers and programmers alike.
Real, actual Markdown support is arriving in Google Docs
Google Docs now supports Markdown, enhancing writing for technical users. Seamless conversion between Markdown and Docs formatting simplifies collaboration and content creation across platforms. Users can soon access this feature in the Tools menu.
Why I Prefer RST to Markdown
The author prefers reStructured Text (rST) over Markdown for technical documentation, citing its complex structure, custom directives, and better management of content across formats, despite its less attractive syntax.
Font with Built-In Syntax Highlighting
The article presents a method for syntax highlighting in hand-coded websites by embedding it into a font using OpenType features, offering a simpler solution with limitations in flexibility and complexity.
- Many users prefer visible syntax in Markdown editing, arguing it enhances clarity and reduces errors.
- Some commenters express frustration with WYSIWYG editors, feeling they obscure the underlying markup and complicate the writing process.
- There is a call for more flexible editing options, such as toggling between Markdown and rendered views.
- Several users advocate for the use of more expressive markup languages in applications where Markdown may not be the best fit.
- Concerns are raised about the readability of Markdown when autoformatters alter whitespace and formatting, impacting the author's intent.
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.
* *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 :)
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.
(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.)
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.
(Could someone please find out which resources we all have to add to ublock to work around this?)
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.
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.
Otherwise, if the usecase is consumption you are better to show the generated output.
Says the inventor of it, 20yrs ago. https://daringfireball.net/projects/markdown/
Maybe it's time to accept that this thing you created is bigger than yourself and it's future is not in your hands.
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.
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.
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).
I just wouldn’t have markdown in my software if I wasn’t going to support a preview.
"<b>: The Bring Attention To element" "<i>: The Idiomatic Text element" "<em>: The Emphasis element" "<strong>: The Strong Importance element"
All the rat poison oriented window managers also have a great point and the ones with no mouse support at all might be perfect for many but it is silly and counter productive not to provide the mouse support because it is an anti pattern and pretend that all the users who need to see the benefits of avoiding the anti pattern, and practice [not] using it, are going to somehow magically end up trying the purist UIs.
One valuable thing about using Markdown as an data storage/exchange format is that it's often easier to manipulate; for example, diffs are normally going to be better, and content edits often easier. Mind you, a proper encoding of a WYSIWYG format, and corresponding tooling, will be better... but for quick-and-dirty that normally works well, Markdown is ultimately pretty good (unfortunately, in my opinion).
And the reason I prefer Markdown, is because it's not proprietary, and Obsidian, my preferred Markdown-Tool, has a different workflow than the usual WYSIWYG-Tools. If Obsidian would use json or yaml for everything, I would still use it. It's just a tool for me, not the goal.
This is my goto React Markdown editor, very solid out of the box and customizable in all sorts of ways
save the current setting to a cookie
some people who stay on the rendered side sometimes forget the syntax, and use the Show Markdown button to check how something was created
For context, I write over 100k words a year. That's something like 150 pages depending on how you format it. This includes both technical documents (which I mainly do in Latex) and more traditional long-form writing (which I do in Markdown).
For technical documents, formatting is very much a key part of the presentation, so I want to see the markup. I mainly use Emacs and I render the PDF from the terminal when I want to see it. Fidelity to the final result is essential, so I don't bother with Latex IDEs (unless I'm doing collaborative editing on Overleaf).
For my long-form writing, I want the markup to get out of the way. I use Markdown because it's simple and portable and generates a large number of formats (via Pandoc); that does NOT mean that I want the asterisks and hash signs and so on staring me in the face. Also, frankly, it's just easier to write when the text looks pretty. For most of this writing I write in Typora (with a nice variable-width font), and then edit in Emacs with the generated PDF side-by-side.
Why bother with Markdown at all? Because Word ultimately gets in the way of me producing nice documents. The fact that I can move my cursor to see exactly what the markup is, and that this markup is simple and straightforward and maps well into what I'm trying to generate, helps me focus on content and avoid distractions. Word has far too many knobs, far too many ways to do something that looks visually correct but generates the wrong markup (especially when you're going to do post-processing in some other tool), and really hinders refactoring (when you need to make global style changes). So I use Markdown, but again, that doesn't mean I want markup staring me in the face.
I'm not sure why people are so incredulous that this is a desirable goal? I mean it should be pretty obvious that the apps would not exist if there wasn't a market for it, so clearly I'm not the only one who feels this way.
Cracking up at this quote
Related
My weekend project turned into a 3 years journey
Anthony's note-taking app journey spans 3 years, evolving from a secure Markdown tool to a complex Electron/React project with code execution capabilities. Facing challenges in store publishing, he prioritizes user feedback and simplicity, opting for a custom online deployment solution.
The Eternal Truth of Markdown
Markdown, a simplified code alternative to HTML, enables diverse document formats from plain text. Despite lacking standardization, it thrives for its adaptability and simplicity, appealing to writers and programmers alike.
Real, actual Markdown support is arriving in Google Docs
Google Docs now supports Markdown, enhancing writing for technical users. Seamless conversion between Markdown and Docs formatting simplifies collaboration and content creation across platforms. Users can soon access this feature in the Tools menu.
Why I Prefer RST to Markdown
The author prefers reStructured Text (rST) over Markdown for technical documentation, citing its complex structure, custom directives, and better management of content across formats, despite its less attractive syntax.
Font with Built-In Syntax Highlighting
The article presents a method for syntax highlighting in hand-coded websites by embedding it into a font using OpenType features, offering a simpler solution with limitations in flexibility and complexity.