Markdown is meant to be shown (2021)
daringfireball.net
daringfireball.net
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.
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.
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.
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.
In my experience underlining is how you bold when you can't bold.
I wasn't disagreeing with that; edited my comment to be clear. Asterisks are emphasis; emphasis is typically italics.
I do think that underscores should have been underlining, but unfortunately that's not what Markdown chose.
Underscores/underline were a hint on a manuscript to the typesetter that you wanted italic (https://en.wikipedia.org/wiki/Underscore). It later became a way to add emphasis (either italic or bold styling) on typewriters as there wasn't a practical way to have bold and italic versions of every character on a mechanical typewriter.
Most professionally typeset content (i.e., optimised for legibility through years of experience rather than just whatever your word processor will allow) will not contain underlined content (https://practicaltypography.com/underlining.html).
What in the world does "words used as words" mean?
I think you are answering my question, but I still don't understand. How else than as words would words be used? Are you saying that the underlining here is serving the purpose of quotation marks?
https://www.chicagomanualofstyle.org/qanda/data/faq/topics/N...
*emphasis* (i.e. italic)
**strong emphasis** (i.e. bold)
You can use underscores in exactly the same way, but the reason I’ve stuck purely to asterisks is that it’s just slightly easier to type and I think it’s slightly more readable when I’m reading an un-rendered Markdown document, so I appreciate the syntax that John Gruber chose here.
No it doesn't. It uses something they call mrkdwn, which is only vaguely superficially similar to Markdown. In most important places, mrkdwn has made different decisions from Markdown. It's a completely different, and far more rudimentary, Lightweight Markup Language.
Nevertheless, good catch
* *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 :)
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...
I agree, however, than my original naive idea of using slashes was not so good. Obviously some practice gives a better understanding of the problem, and nowadays I see it differently. The slash is too common in written language; it's actually a good thing that unintended italics are not introduced after writing some trivial slashed term in a text, such as "he/him".
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).
For example when I have GPTs spit out tables for researching a topic.
https://i.imgur.com/4gIGYLu.png
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.
(setq org-hide-emphasis-markers t)
M-x visible-mode
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.)
Please stop doing that, prettier.
...Arguably, the reason HTML has collapsible whitespace is to allow writing readable source, and once upon a time it was more common to see HTML produced in a way that didn't get in the way of this (e.g. paragraphs and indentation indicated primarily via whitespace with only opening `<p>` and `<li>` tags). But that ship sailed; tooling long ago coalesced around more rigid conventions, and thus the need for Markdown emerged. Throwing those advantages away raises the question of why bother using Markdown at all.
> I’ve written a text-to-HTML formatting tool called Markdown
... which kinda suggests to me it's meant to be rendered.
Markdown's major advantage is that it's (mostly) readable as plaintext (essentially a graceful degradation), but evidenced by how most tools using it render Markdown into HTML instead of showing it unrendered, it doesn't seem like people prefer reading it.
The people who replied to you are saying that it's nonetheless (also) meant to be read as-is -- because that's relevant to whether or not a markdown formatter should try to preserve readability, which was the topic at hand.
Now the point is - markdown formatters only format things which won't have an effect in the rendered HTML, so why does it matter? Do you have some meaningful information encoded in markdown which does not translate to HTML? That sounds like a clear anti-pattern, since by rendering to HTML you lose it.
If it's relevant for you, great! This thread is me saying it ought to be configurable either way.
> so why does it matter?
Readability, per the whole thread.
There is no "source markdown". Markdown is meant to be formatted to be read, without any intermediate step. "Prettifiers" like github etc are just converting the markdown into "styled" text. The format was always meant to be read as is.
> "Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions."
Which is to say there isn’t any such thing as “source Markdown” and “rendered Markdown”. Markdown is the source, HTML is the output, although you can make your own parser output to whatever you want.
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.
The stated philosophy behind Prettier is to end arguments within a team about how to format code, which... Given Markdown is already heavily constrained, barely applies; unlike other languages supported by Prettier, there are precious few adjustments made to Markdown that are clearly intentionally made in pursuit of consistent readability - indeed, if I recall correctly the Prettier Markdown engine is mostly just a round-trip through the remark.js parser and stringifier, and the results reflect this - the results look mechanical, and it is just as likely to eliminate whitespace that lends clarity as it is to add it (if not, as the GP suggests, more likely).
Sadly, there are remark.js plugins that could have been used to e.g. enforce consistent use of whitespace without stripping everything down to the bare minimum, but last I looked the Prettier folk were pretty hostile toward any suggestions that their (default, bare-minimum-effort) "style" was at all problematic.
const matrix = [
1, 0, 0,
0, 1, 0,
0, 0, 1,
]
I can't imagine how it works for people who aren't pretty good at the syntax.
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.
If you're writing a new sentence in MSWord, you type "Emphasize words <Ctrl-I>like this<Ctrl-I>."
If you write a new sentence in Markdown, you type "Emphasize words *like this*."
The keys are neighbors even, at least in a US keyboard layout, so there is not a reason most US users would say it's "faster" to type * than Ctrl-I. (And if other layout users disagree, okay, but I don't think that was in the scope of the original point.)
The problem with Word-like editor styling is exactly that the boundaries are invisible, and the style is applied destructively to everything within highlighted range, instead of non-destructively by the range itself. What I mean is, if in the example above, I want to change the emphasis to only italicize "this", I can kill the first * and place it a word later. In Word-style editing, I'll have to highlight the whole "like " sequence and un-italicize it, hoping I didn't miss a space or a dot that invisibly retains the italics and then screw up editing for you down the line.
Is this very different from "<left> <Ctrl+Shift+left> <Ctrl+Shift+Left> <Ctrl+I>"?
What I also know is that when out company switched to visual editor only, people stopped using these. They stopped writing long texts - and those were those the most valuable.
(it also ought to italicize the selection when there's an active selection, but i haven't implemented that yet)
i think this is a superior interaction paradigm to the paradigm where ctrl-i sets an italics mode that doesn't visibly change anything near the cursor, but affects the future text you type. that design not only usually requires more keystrokes but causes mode errors. this is how ctrl-i and ctrl-b should always have worked, and if larry tesler had thought of the idea by 01983, that's how they always would have worked
however, the keystroke ctrl-i is easier to type than the keystroke alt-*
I have a tooling issue with your method, perhaps in the same manner as you feel about C-i. To me "italicize $count previous words" makes far more sense than expanding the region on repeated calls. Although to be fair I can wrap over visual mode for that functionality which would feel more comfortable to me; "ge" end of previous word, "v", $navigation, ...
My point - to the extent I have one - is that there is probably a degree of personal comfort that colors our reactions to people using C-i.
¹ Basically "imap <C-S-8> <Esc>bcw*<C-r>-*<C-o>w". I'll give it some more thought, along with adding v:count and non-* support, before it hits my vimrc.
The shift key is right under my pinkie, a bit easier than the CMD key on my Mac (much less the Ctrl) for me.
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.
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.)
(This is part of the background work for [Monnier’s paper with him
about Elisp’s history][3] for HOPL ’20.)
...
[3]: https://dl.acm.org/doi/pdf/10.1145/3386324 (Evolution of Emacs Lisp, by Stefan Monnier and Michael Sperber)
(it ought to use the selection as the link text if there is one, and to find an existing block of footnotes to add the footnote to if there is one, but i haven't implemented those features)
the upshot of this is that in the above, after typing 'history', i pressed ctrl-alt-] and kept pressing ] until the link had engulfed monnier's name
emacs markdown-mode does also automatically syntax-highlight links, headers, bulleted lists, italic, bold, typewriter code, and markdown linebreaks, and it has a command (the also rather horrible keybinding ctrl-c ctrl-o) to open a link. if the link is to a local file, it opens it in emacs rather than your browser. it also uses the tab key to expand and collapse headers, and of course it always has emacs's instantaneous full-text search. but the formatting is much uglier than obsidian's
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.
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.
Says the inventor of it, 20yrs ago. https://daringfireball.net/projects/markdown/
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.
https://www.reddit.com/r/todayilearned/comments/azevs3/til_t...
> Of course you should understand that I ate the column only because the Internet, as far as I can tell, did not suffer a gigalapse during 1996 -- a billion lost user*hours in a single outage. The Internet has indeed bogged down (hit STOP much?) and has indeed suffered large outages (the biggest being a 118 megalapse at AOL in August)
He was only wrong by a factor of 9.
You can pull up any individual Daring Fireball article and append .text to the URL to read the Markdown source, but you don’t necessarily want to read Daring Fireball (or anything) like that.
Similarly, I think Markdown gets misused in a lot of places it doesn’t really belong. It’s handy, sure, but there’s also nothing wrong with just making a good WYSIWIG editor for people rather than telling them they have to use Markdown. That’s just my opinion, but Gruber has expressed similar opinions elsewhere.
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.
How about, "Coaching clients to ask for new DB fields instead of overloading existing ones?"
But I did have a client who really hated markdown because she couldn’t make colors red.
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.
You can also set Slack to not render the markdown until the message is sent, which I would thoroughly recommend
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.
Switch the dropdown from "Live preview" to "Source mode"
You can also click the three dots in the upper right corner and select source mode.
I open sourced my css snippets repo, and the first CSS rule in this file in my minimal theme CSS snippets repo resets font sizes in source view so font sizes are the all the same:
https://github.com/replete/obsidian-minimal-theme-css-snippe...
"<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.
But one of the key features of Markdown (and, indeed, most tech such as programming langauges) is the ubiquity. It's really hard to overcome the fact that almost every platform can export/import markdown.
Why are almost all of those light formatters removing your line breaks? Everytime someone mentions some markdown variant (and there are many of them!) and I look up the syntax description, it shows that newlines are being ignored.
If it's trying to be plain text, at least behave like plain text, and don't remove newlines in a shopping list like this (just like hacker news also does with its comments):
-eggs -milk -flour -water
BBCode has it right.
This is also why the parsing ambiguity/backtracking ends up occurring - humans can read plaintext and do pattern matching with context/attention whereas parsing algorithms have a hard time.
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
I don't think I'd ever prefer seeing raw markdown over rendered documents when browsing GitHub repositories for example.
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
Based on his interaction with the CommonMark people I would characterize it more as overly possessive.
As someone who contributed a bit to the early CommonMark spec I think some of us were really doing it the shitty way towards Gruber.
How would the Rust people react if we created a "Standard Rust" language?
https://daringfireball.net/projects/markdown/
>Markdown is free software, available under a BSD-style open source license.
John Gruber's markdown is unmaintained (last updated in 2004), free software, which many people have contributed to to fix oversights and extend its capabilities. This is exactly how fsf is supposed to work.
It was about the _Name_ , never about the syntax/implementation.
Gruber was very clear with his license and regular words that he did not allow the usage of the name in a manner which would cause people to be confused or suggest that it was an official implementation.
You could maybe patent Markdown (given the amount of trash software patents I've seen I wouldn't be surprised) but (1) it's not patented AFAIK and (2) it's become so common (mark, heh) that I don't think it could be patented anymore.
You could say Markdown is covered as a trademark even if not officially registered maybe? I don't know the specifics though, could anyone chime in? (this is complicated further by the different jurisdictions). But my understanding of the general idea is that if your trademark becomes common (which I guess happened?) or you don't actively defend it (which is what Gruber was trying to do fighting Standard Markdown), you lose it.
So, to summarize, I think he was right to be angry (in a moral way) but that's possibly the only right he had in the literal sense. Which is more than enough of course.
If the crucial part here is the fact that he apparently already copyrighted the name then that seems kind of like begging the question. I wouldn’t copyright a bland name like that which has no connection to my own person. (Maybe I would copyright something like keybord-lang though...)