The Curse of Markdown(codehike.org)
codehike.org
The Curse of Markdown
https://codehike.org/blog/the-curse-of-markdown
119 comments
Markdown has always supported direct raw HTML in it. I don't see any gulf or sudden jump in cost. Don't be a Markdown purist. Even John Gruber, the creator of Markdown, is not a Markdown purist. Go look at the Markdown source of his blog and you will see that he frequently just uses raw HTML. He doesn't even do multi-paragraph ordered lists in Markdown, and chooses to write <ol><li><p> instead. And he also uses <a><img> for clickable images. You can append ".text" to any of his blog article to get the Markdown source; example https://daringfireball.net/2020/10/the_iphone_12_and_iphone_...
On the note of embedding HTML in Markdown, I think it'd be cool if it were just as easy to embed Markdown in HTML. Something akin to a <markdown> tag.
Markdown makes it easy to write formatted content at the cost of initial compiler setup, HTML is 0-cost setup but takes some effort to write formatted content. With a <markdown> tag one could start with vanilla HTML at zero cost, use all its features straight away, but not have to type HTML for the simple, "content" parts of a site.
EDIT: there seem to be web components for this already:
- https://github.com/xan105/web-component-markdown
- https://www.webcomponents.org/element/zero-md
- https://www.webcomponents.org/element/@vanillawc/wc-markdown
Markdown makes it easy to write formatted content at the cost of initial compiler setup, HTML is 0-cost setup but takes some effort to write formatted content. With a <markdown> tag one could start with vanilla HTML at zero cost, use all its features straight away, but not have to type HTML for the simple, "content" parts of a site.
EDIT: there seem to be web components for this already:
- https://github.com/xan105/web-component-markdown
- https://www.webcomponents.org/element/zero-md
- https://www.webcomponents.org/element/@vanillawc/wc-markdown
Take a look at https://www.tducret.com/pure-markdown
It's just a single JS script import, and then plain Markdown.
You can host it as-is, no build required (à la Jekyll, Hugo...).
You can verify the content with : curl https://www.tducret.com/pure-markdown/
You can verify the content with : curl https://www.tducret.com/pure-markdown/
That sounds like a good idea, until you remember that there is no officially agreed upon markdown spec. For content authors it'd be both fantastic if browsers could just go "you guys go fight it out, we're just gonna go with GitHub flavored markdown" but at the same time for browser makers that's taking a position on something that they have no stake in.
So writing or using someone else's custom element is pretty much your only option here.
So writing or using someone else's custom element is pretty much your only option here.
There is a Markdown spec: https://commonmark.org
Although of course in practice, commonmark renderers are not plentiful or up to date. In my experience, most library authors end up just implementing the bits of Markdown they care about and the behavior they prefer for the ambiguous parts.
Although of course in practice, commonmark renderers are not plentiful or up to date. In my experience, most library authors end up just implementing the bits of Markdown they care about and the behavior they prefer for the ambiguous parts.
There are multiple markdown specs. This is one of them, probably the most well-known, but certainly not the only one.
“This is my Markdown. There are many like it but this one is mine.”
yeah, I wasn't hypothesizing this as something that should be added natively to browsers. Web is complicated enough officially supporting 3 languages (or 6, if you consider wasm, webgl and wgsl)
Though for what its worth, "no official agreed upon spec" didn't stop browsers before haha
Though for what its worth, "no official agreed upon spec" didn't stop browsers before haha
It will probably never happen, because the browser would need to translate to HTML anyway, before rendering it. At that point it could simply be done beforehand on the server, not putting more tasks onto the browser and adding the complexities of HTML inside md inside HTML inside md ... and so on.
> Even John Gruber, the creator of Markdown, is not a Markdown purist. Go look at the Markdown source of his blog and you will see that he frequently just uses raw HTML.
John Gruber is the worst possible authority to reference here. He’s a bad steward of the standard and Markdown is popular despite him, not because of him. His own implementation has bugs that will never be fixed, doesn’t support features we all take for granted as basic Markdown, and he refused to even acknowledge when someone wanted to make a proper standard out of it. If Markdown were left to him, none of us would be using it and would have come up with something inspired by it but probably better and without a myriad of competing implementations with different levels of support.
> Go look at the Markdown source of his blog and you will see that he frequently just uses raw HTML.
In situations where, if he used any parser other than his own stagnant code, the whole post could have been written in Markdown. For crying out loud, in the page you linked he has Markdown tables (which his parser does not support) inside HTML comments followed by HTML tables. Daring Fireball is a popular site, but it’s not an example of good design or content structuring. To this day it’s still annoying to read on mobile.
John Gruber is the worst possible authority to reference here. He’s a bad steward of the standard and Markdown is popular despite him, not because of him. His own implementation has bugs that will never be fixed, doesn’t support features we all take for granted as basic Markdown, and he refused to even acknowledge when someone wanted to make a proper standard out of it. If Markdown were left to him, none of us would be using it and would have come up with something inspired by it but probably better and without a myriad of competing implementations with different levels of support.
> Go look at the Markdown source of his blog and you will see that he frequently just uses raw HTML.
In situations where, if he used any parser other than his own stagnant code, the whole post could have been written in Markdown. For crying out loud, in the page you linked he has Markdown tables (which his parser does not support) inside HTML comments followed by HTML tables. Daring Fireball is a popular site, but it’s not an example of good design or content structuring. To this day it’s still annoying to read on mobile.
100% this -- we tried to work with JG to create and support a Markdown standard when we formalized "GitHub flavored Markdown" and got the exact opposite reaction many of us expected. Even using the name in any context was seen as a slight.
More context:
https://github.blog/engineering/user-experience/a-formal-spe...
https://github.github.com/gfm/
More context:
https://github.blog/engineering/user-experience/a-formal-spe...
https://github.github.com/gfm/
Dude created a simple tool based on email conventions of the time and released it to the world for free and it's still with us, used all over. And you're here crying that he didn't want to work with you? Did you think he was somehow obligated to? How incredibly entitled.
It's open source, so you do what you do. That's the good and bad of it. No one owes you a god damned thing.
It's open source, so you do what you do. That's the good and bad of it. No one owes you a god damned thing.
I think you're missing much of the context and are misrepresenting what happened.
As far as I'm aware, there was no crying he didn't want to work with people, but there was a frustration that he was not open to having a Markdown "standard". To the point where he actively opposed efforts to standardize it, at least under the name Markdown[1].
This is legally and technically fine, as he owns a trademark for Markdown, but when you combine the inconsistent application of that trademark (GitHub Flavored Markdown is seemingly fine, but Common Markdown was not), along with him calling it "Jeff Atwood's crusade" and mocking the effort[2], it's not a great look and resulted in quite a few frustrated people.
As an open source project, you're right that he doesn't owe anything to anyone, but that doesn't mean people have to be entirely happy about how the situation was handled either.
[1]: https://blog.codinghorror.com/standard-markdown-is-now-commo...
[2]: https://soundcloud.com/thetalkshow/ep-88-cat-pictures-side-1, around 1:15
As far as I'm aware, there was no crying he didn't want to work with people, but there was a frustration that he was not open to having a Markdown "standard". To the point where he actively opposed efforts to standardize it, at least under the name Markdown[1].
This is legally and technically fine, as he owns a trademark for Markdown, but when you combine the inconsistent application of that trademark (GitHub Flavored Markdown is seemingly fine, but Common Markdown was not), along with him calling it "Jeff Atwood's crusade" and mocking the effort[2], it's not a great look and resulted in quite a few frustrated people.
As an open source project, you're right that he doesn't owe anything to anyone, but that doesn't mean people have to be entirely happy about how the situation was handled either.
[1]: https://blog.codinghorror.com/standard-markdown-is-now-commo...
[2]: https://soundcloud.com/thetalkshow/ep-88-cat-pictures-side-1, around 1:15
> As an open source project
But it’s not an open-source project. It’s a download link to a Perl script which is never updated and effectively no one uses.
There’s currently zero value to the code he wrote or the reference in his page. The only thing of worth that remains of his original implementation is the concept and the most basic syntax.
But it’s not an open-source project. It’s a download link to a Perl script which is never updated and effectively no one uses.
There’s currently zero value to the code he wrote or the reference in his page. The only thing of worth that remains of his original implementation is the concept and the most basic syntax.
The point is Gruber was contacted out of courtesy, his name as the initial author carrying some weight in people's minds, and he reacted in an openly hostile and mocking way.
I listen to a few podcasts that Gruber is a friend of, but he’s always struck me as a bit vapid and haughty. He always seems to reference his own influence, which he seems to have earned by…coming up with a handful of basic text markup syntax and writing Apple hagiographies?
I always wondered why anybody would "support" or subscribe to the microblog of someone whose profession seems to be "write about Apple, mostly defending them". And not in any detailed long form, either.
I don't enjoy the fact that he's obviously biased and defends Apple too often, and occasionally shows his lack of technical understanding. But this man's job is writing and he writes better than 90% of blog posts posted on HN. And he has plenty of long form posts. His iPhone reviews are often longer than most tech journalists' reviews. I often disagree with the contents of his writing, but I do have a soft spot for people who wield language well.
Gruber also had a famously snotty reaction to Jeff Atwood (of coding horror, stackoverflow, Discourse and others) contacting him about standardizing markdown.
I won't rehash it here, it's been mentioned before both here and in Coding Horror (Atwood's blog)
I won't rehash it here, it's been mentioned before both here and in Coding Horror (Atwood's blog)
At that point, why aren't you just writing HTML?
Markdown is really just a way of making the average, text, bit of HTML a little bit easier to read and write. Even when you're including some HTML in it, it still has that advantage over raw HTML.
<p>because, it is <i>really</i> awkward</p>
All the hoops you have to jump through with Markdown seem more awkward to me than a few extra characters.
but you jump through those hoops during setup, vs seven extra characters every paragraph
But then you just end up writing HTML anyways.
the output is html, but when you're writing markdown thought flows to output more seamlessly, with fewer characters vs with having to close italics with the more awkward </i>. yeah in the end that goes through a tool and it outputs html, but it's about when I'm trying to get the ideas out of my head and onto the page.
> I don't see any gulf or sudden jump in cost.
Then you missed the core point of the article, so I'll try and rephrase it:
While you're staying in Markdown-only land (the left part of the article's graph halfway down the article: low-medium richness (horizontal), very low complexity (vertical)), you are not learning HTML.
You miss the "onboarding" process to the richness of HTML, so when you reach the limits of what Markdown can do, and suddenly you need something medium-rich... you have to play catch-up to learn all the HTML that you avoided by sticking to Markdown. That's the gap.
The fact that Markdown supports in-line HTML allows you to bridge the gap, but is irrelevant to the point.
Then you missed the core point of the article, so I'll try and rephrase it:
While you're staying in Markdown-only land (the left part of the article's graph halfway down the article: low-medium richness (horizontal), very low complexity (vertical)), you are not learning HTML.
You miss the "onboarding" process to the richness of HTML, so when you reach the limits of what Markdown can do, and suddenly you need something medium-rich... you have to play catch-up to learn all the HTML that you avoided by sticking to Markdown. That's the gap.
The fact that Markdown supports in-line HTML allows you to bridge the gap, but is irrelevant to the point.
You're not learning html when you write react horror shows either.
it's a space that broke <A /> because they're too useful and needed a broken react special version.
it's a space that broke <A /> because they're too useful and needed a broken react special version.
Yeah, I don't buy the theory either. Markdown has always made it easy to just drop in a bit of HTML wherever you need it, and major dialects like Pandoc Markdown support even more. You can set class, ID, and data-attributes on most elements, such as links, or write any div/span placeholder you need natively. (I don't even bother to use the native syntax because writing a '<div class="foo">bar</div>' is so easy.) What 'rich' features is that impeding?
I can say that on my website, which is certainly 'richer' than most Markdown-oriented websites, we scarcely ever think about Markdown as a limitation to implementing a feature. Nor was it a serious hindrance at any point. There have been issues, sure, but pretty much never do we tear our hair out going, 'how can we possibly implement transclusion properly, when the source is written in Markdown rather than Asciidoc??? Woe is us!' That's just not a thing.
When we have issues, it's almost always related to something about the Pandoc internal API design choices (essentially unrelated to any syntactic sugar and would be equally true if we were starting from a different input type) or the sheer difficulty of implementing anything well & reliably cross-platform/device/mode. The Markdown part of our discussions usually boils down to a debate over the naming of a class. Because setting the class on whatever element is a non-problem, already solved, and we move on to the real challenges to adding a rich feature.
To whatever extent his imaginary gap exists in reality, I would bet it has far more to do with dynamics around websites which happen to use Markdown, like trying to cater to the lowest-common denominator and banning HTML fragments, and stuff like that.
I can say that on my website, which is certainly 'richer' than most Markdown-oriented websites, we scarcely ever think about Markdown as a limitation to implementing a feature. Nor was it a serious hindrance at any point. There have been issues, sure, but pretty much never do we tear our hair out going, 'how can we possibly implement transclusion properly, when the source is written in Markdown rather than Asciidoc??? Woe is us!' That's just not a thing.
When we have issues, it's almost always related to something about the Pandoc internal API design choices (essentially unrelated to any syntactic sugar and would be equally true if we were starting from a different input type) or the sheer difficulty of implementing anything well & reliably cross-platform/device/mode. The Markdown part of our discussions usually boils down to a debate over the naming of a class. Because setting the class on whatever element is a non-problem, already solved, and we move on to the real challenges to adding a rich feature.
To whatever extent his imaginary gap exists in reality, I would bet it has far more to do with dynamics around websites which happen to use Markdown, like trying to cater to the lowest-common denominator and banning HTML fragments, and stuff like that.
So? I could write my blog post in raw HTML without using any markdown at all. But we don't, because raw HTML is a bad tool for composing rich content.
The kind of things I want to be able to do (that markdown makes hard):
- Make a standard component for embedded images, which supports clicking the image to see it full-screen.
- Make "boxes", showing certain kinds of content. This is useful for diagrams, commentary, code, formulas, and more depending on what you're doing.
- Run code when building the page which can load external data and display it however I want. For example, I wrote a paper using typst recently. I have some data in a JSON file. My typst paper contains code to read in the JSON file and embed some of the values into a table in the output.
- Embed raw SVGs into the output, in an svg tag.
- Have programmatic content - eg, onclick handlers, hover states, etc.
- Make a table of contents (I think GFM supports this, but I don't think its a standard markdown feature)
- Have generated section titles (Eg "3.a Benchmark results")
- Make a webpage which contains content from a lot of markdown files in a folder. Each of those files may need custom ... well, everything.
- Use custom CSS styles. Styles might be local (just this element) or global across the page.
- Use extensions / plugins for things like programmatic diagrams
Raw HTML is a complete non-answer to this stuff. Its the sort of answer that makes me question if you've done any serious writing at all. Like, your comment reads to me as the writing equivalent of arguing that C is the best programming language because - if you need anything thats not in C, you can write it in assembly.
What I really want is some combination of markdown + react. Typst is close - or, it will be close once it supports HTML output. But markdown simply isn't powerful enough for serious writing.
The kind of things I want to be able to do (that markdown makes hard):
- Make a standard component for embedded images, which supports clicking the image to see it full-screen.
- Make "boxes", showing certain kinds of content. This is useful for diagrams, commentary, code, formulas, and more depending on what you're doing.
- Run code when building the page which can load external data and display it however I want. For example, I wrote a paper using typst recently. I have some data in a JSON file. My typst paper contains code to read in the JSON file and embed some of the values into a table in the output.
- Embed raw SVGs into the output, in an svg tag.
- Have programmatic content - eg, onclick handlers, hover states, etc.
- Make a table of contents (I think GFM supports this, but I don't think its a standard markdown feature)
- Have generated section titles (Eg "3.a Benchmark results")
- Make a webpage which contains content from a lot of markdown files in a folder. Each of those files may need custom ... well, everything.
- Use custom CSS styles. Styles might be local (just this element) or global across the page.
- Use extensions / plugins for things like programmatic diagrams
Raw HTML is a complete non-answer to this stuff. Its the sort of answer that makes me question if you've done any serious writing at all. Like, your comment reads to me as the writing equivalent of arguing that C is the best programming language because - if you need anything thats not in C, you can write it in assembly.
What I really want is some combination of markdown + react. Typst is close - or, it will be close once it supports HTML output. But markdown simply isn't powerful enough for serious writing.
> The impact of Markdown becomes clear if we plot a random sample of content websites. (Disclaimer: the data is made-up, based on my perception of the state of the web)
It makes sense that your perception of the web has driven you to create a new tool and market it with a think piece. But to expand that to suggest you have effectively realized and filled a new vector space in the web is excessive
>That sparse area just beyond the limits of Markdown is of vital importance to the web. These websites are not only a joy to read but also the ones that explore the web's possibilities, embracing the medium and evoking a truly web-native feel.
>Currently, these websites are outliers created by individuals who care deeply about the reader's experience or by companies willing to invest extra effort. We need more of them.
Interesting to me that you have added "focus on this paragraph" coloring to your site. I'm not against that in principle, but you have placed it farther up the page than I prefer to read and scroll. So you care deeply about my experience, have created a whole tool to inhabit an area of web design that you think is undeserved, rationalize it based on feels, and, for me, deliver a poorer experience to show it off.
"The Website Wasteland", as you call it, is a good thing if this is the result of populating it.
It makes sense that your perception of the web has driven you to create a new tool and market it with a think piece. But to expand that to suggest you have effectively realized and filled a new vector space in the web is excessive
>That sparse area just beyond the limits of Markdown is of vital importance to the web. These websites are not only a joy to read but also the ones that explore the web's possibilities, embracing the medium and evoking a truly web-native feel.
>Currently, these websites are outliers created by individuals who care deeply about the reader's experience or by companies willing to invest extra effort. We need more of them.
Interesting to me that you have added "focus on this paragraph" coloring to your site. I'm not against that in principle, but you have placed it farther up the page than I prefer to read and scroll. So you care deeply about my experience, have created a whole tool to inhabit an area of web design that you think is undeserved, rationalize it based on feels, and, for me, deliver a poorer experience to show it off.
"The Website Wasteland", as you call it, is a good thing if this is the result of populating it.
well put, and I had thoughts just like this while reading the linked article.
I find that most of the use cases in that 'wasteland' would be made better by reducing the fluff and focusing on content. In my younger days, I chafed at the restrictions of Markdown and similar tools. However I now appreciate that the results are almost always easier to read.
I find that most of the use cases in that 'wasteland' would be made better by reducing the fluff and focusing on content. In my younger days, I chafed at the restrictions of Markdown and similar tools. However I now appreciate that the results are almost always easier to read.
Eh, maybe that's excessive for you and the kind of writing you do. But I think the author is right - there's plenty of valuable writing where being able to customize the page more is valuable.
The most obvious example to me is academic articles - where you need footnotes, figures, algorithm blocks, appendicies, math, numbered sections, and so on. Markdown doesn't support any of that stuff and latex is horrible on the web. It would be great to have something with support for those features, but that also supported HTML output.
But, there's plenty more examples where being able to make richer content than markdown supports is super valuable. For example, Bartosz Ciechanowski's blog is incredible:
https://ciechanow.ski/gps/
Doing anything like this in markdown is hard. You're kind of fighting the tool. The ideal tool would support custom components + custom styling - which aren't supported at all by markdown.
This whole comment thread is weirdly down on the article. I suspect most people have simply never come up against markdown's limitations while doing technical writing. They're quite severe whenever the output of your documentation needs to be a rich website or paper, not just a documentation file in a github repository.
The most obvious example to me is academic articles - where you need footnotes, figures, algorithm blocks, appendicies, math, numbered sections, and so on. Markdown doesn't support any of that stuff and latex is horrible on the web. It would be great to have something with support for those features, but that also supported HTML output.
But, there's plenty more examples where being able to make richer content than markdown supports is super valuable. For example, Bartosz Ciechanowski's blog is incredible:
https://ciechanow.ski/gps/
Doing anything like this in markdown is hard. You're kind of fighting the tool. The ideal tool would support custom components + custom styling - which aren't supported at all by markdown.
This whole comment thread is weirdly down on the article. I suspect most people have simply never come up against markdown's limitations while doing technical writing. They're quite severe whenever the output of your documentation needs to be a rich website or paper, not just a documentation file in a github repository.
Had the same thought. It’s not that you can’t get an index out of Pandoc, it’s that it’s a bridge just slightly too far unless you’re really committed, and then you have a long road ahead of you.
> A great example of a rich content website is the Tailwind CSS landing page.
This is a pretty bad example, right? It is the landing page for some web framework or whatever, that shows you it can make over-complicated websites by being itself an over-complicated website. It is being good at its job in some sense no matter what it does, because the thing it is showing is… the thing that it does.
But, this doesn’t show any evidence that any other websites need to be as interactive and dynamic as the tailwind website (they don’t).
Websites are all over-complicated, markdown is no curse. If this wall is true, it is a blessed line of defense.
This is a pretty bad example, right? It is the landing page for some web framework or whatever, that shows you it can make over-complicated websites by being itself an over-complicated website. It is being good at its job in some sense no matter what it does, because the thing it is showing is… the thing that it does.
But, this doesn’t show any evidence that any other websites need to be as interactive and dynamic as the tailwind website (they don’t).
Websites are all over-complicated, markdown is no curse. If this wall is true, it is a blessed line of defense.
Tailwind is a styling system. And it makes sense that its website shows off what it can do.
It has nothing to do with complicated.
It has nothing to do with complicated.
Yes, it is a bit bizarre.
The authors solution is more frame works to bridge the gap, but the only evidence for something beyond that gap is itself a framework.
Doubly troubling is that theyre pushing their own frame work, that presumably they think solves some real world problem, but can point to a concrete example of what theyre solving.
Finally. If you want to foist a complicated website on a user, you can't complain about complexity in the creation of the site. Quite why a dev feels the need to push a framework, to make a fancy site, just for me to install an ad blocker to remove the fancy (I assume thats what were really talking about here) to get back to markdown levels. I don't know.
The authors solution is more frame works to bridge the gap, but the only evidence for something beyond that gap is itself a framework.
Doubly troubling is that theyre pushing their own frame work, that presumably they think solves some real world problem, but can point to a concrete example of what theyre solving.
Finally. If you want to foist a complicated website on a user, you can't complain about complexity in the creation of the site. Quite why a dev feels the need to push a framework, to make a fancy site, just for me to install an ad blocker to remove the fancy (I assume thats what were really talking about here) to get back to markdown levels. I don't know.
That made me chuckle. It is like showing how good my programming language by building an interpreter.
Everyone else in the world - and I mean everyone - who is not a software engineer - does not use Markdown.
There is a reason for that. And it's not because they're all stupid and software engineers are all geniuses.
It's because normal people do not want to spend their day wasted in minutia, carving out huge chunks of technical jargon, just to get some words on a page to show up with a certain layout and format.
They want to highlight some text, and click the Bold button, or maybe Ctrl+B, and see the text become bold. They don't want to write code. They want to just make a fucking document, so they can get on with their day.
We have had programs that do this for about 40+ years now. They are called word processors and presentation tools. They work very well, and require absolutely zero code or weird characters.
But software engineers are so insanely out of touch, so cluelessly locked into their web browsers, that they literally cannot imagine a universe in which a person isn't writing code to get some text to show up on a screen, formatted and laid out.
It literally feels like everyone in this industry is insane.
There is a reason for that. And it's not because they're all stupid and software engineers are all geniuses.
It's because normal people do not want to spend their day wasted in minutia, carving out huge chunks of technical jargon, just to get some words on a page to show up with a certain layout and format.
They want to highlight some text, and click the Bold button, or maybe Ctrl+B, and see the text become bold. They don't want to write code. They want to just make a fucking document, so they can get on with their day.
We have had programs that do this for about 40+ years now. They are called word processors and presentation tools. They work very well, and require absolutely zero code or weird characters.
But software engineers are so insanely out of touch, so cluelessly locked into their web browsers, that they literally cannot imagine a universe in which a person isn't writing code to get some text to show up on a screen, formatted and laid out.
It literally feels like everyone in this industry is insane.
> It's because normal people do not want to spend their day wasted in minutia, carving out huge chunks of technical jargon, just to get some words on a page to show up with a certain layout and format.
> They want to highlight some text, and click the Bold button, or maybe Ctrl+B, and see the text become bold.
They do not. No normal person has ever said how happy they were that they could highlight text and click a button, and certainly not that they typed Ctrl+B. Normal people do not type Ctrl+anything.
Normal people don't type text at all, but if you find the most normie internet forum you can think of - one where people talk about car parts or who the Khardasians are dating or something - you'll find it has some kind of text markup format, and the most prolific users of that forum use the markup format rather than the WYSIWTF editor that craps up their formatting too much. And if you ever find a topic with two competing norie fora, you'll find the people on the one whose text markup format is more markdown-like will be happier than the people on the one whose text markup format is less markdown-like.
> They want to highlight some text, and click the Bold button, or maybe Ctrl+B, and see the text become bold.
They do not. No normal person has ever said how happy they were that they could highlight text and click a button, and certainly not that they typed Ctrl+B. Normal people do not type Ctrl+anything.
Normal people don't type text at all, but if you find the most normie internet forum you can think of - one where people talk about car parts or who the Khardasians are dating or something - you'll find it has some kind of text markup format, and the most prolific users of that forum use the markup format rather than the WYSIWTF editor that craps up their formatting too much. And if you ever find a topic with two competing norie fora, you'll find the people on the one whose text markup format is more markdown-like will be happier than the people on the one whose text markup format is less markdown-like.
forum? Instagram is the mainstream product you're looking for, and the text rendering there is decidedly GUI based and not markdown-esque
Instagram does not offer "highlight some text, and click the Bold button, or maybe Ctrl+B". The normal way to put bold text on Instagram is to use an online "bold text generator" and copy-paste from there. I struggle to imagine that it's that way because people like doing that.
From a quick search only "mainstream social media" which offers native bold functionality is WhatsApp. And it uses markdown-style.
From a quick search only "mainstream social media" which offers native bold functionality is WhatsApp. And it uses markdown-style.
Everyone and that even includes many software developers uses unprofessional tools. Wysiwyg and pressing buttons are easier when you start. Text-only sources and mark up (like Markdown...) are more powerful when requirements grow.
Just as an example: We use Google's office suite in our company because there are some users who believe it is more user-friendly than storing text and a proper version control. For version control Google offers named versions. Last week some Google sheet reached its 16th version. Well, would have reached, if Google did not limit the number of named versions to 15. You cannot run a business with serious audit trail requirements using so-called user-friendly "everyone uses" tools. Everyone has horrible standards and inappropriate IT continues to lower them. It's a fact, but not a fact anyone should praise.
Just as an example: We use Google's office suite in our company because there are some users who believe it is more user-friendly than storing text and a proper version control. For version control Google offers named versions. Last week some Google sheet reached its 16th version. Well, would have reached, if Google did not limit the number of named versions to 15. You cannot run a business with serious audit trail requirements using so-called user-friendly "everyone uses" tools. Everyone has horrible standards and inappropriate IT continues to lower them. It's a fact, but not a fact anyone should praise.
Hi. I'm not a software engineer. I write a lot, and I use Markdown for most of it, including in professional context as a team manager. Even for things as simple as call notes (just a bullet list, but that's THE POINT).
This is a really stupid take.
This is a really stupid take.
I think this is because normal people dont use git and/or console text editors. Its a powerful combination that makes markdown useful.
> They want to just make a fucking document, so they can get on with their day.
This is exactly why I ditched WYSIWYG long before I knew how to code.
This is exactly why I ditched WYSIWYG long before I knew how to code.
Extended (or rather, distended) Markdown flavors always make me queasy, and I don't love the snippet from Code Hike. In my mind, Markdown is fundamentally intended to be lightweight--something for a Reddit post or a blog comment. Heavily extending its syntax instead of choosing a saner syntactic basis strikes me as ill-advised. But one can't deny the advantages for adoption to be had from using Markdown as a starting point, and the project appears to be very popular, so perhaps worse is better.
> Currently, these websites are outliers created by individuals who care deeply about the reader's experience or by companies willing to invest extra effort. We need more of them.
The premise is deeply flawed. Richness is not a sign of care or investment in the reader's experience. Often it's exactly the opposite. Often richness is gaudy and pointless while simplicity makes content clearer and more useful. Maybe this is a great and valuable tool for certain use cases, but the justification here is weak.
The premise is deeply flawed. Richness is not a sign of care or investment in the reader's experience. Often it's exactly the opposite. Often richness is gaudy and pointless while simplicity makes content clearer and more useful. Maybe this is a great and valuable tool for certain use cases, but the justification here is weak.
Yup, the author's website is an example of this. Their flashy graphic that animated while scrolling did nothing for the content. In fact, their font was so small I could not read the text without zooming in, which completely contradicts the whole premise of the piece -- that a lack of "richness" is preventing ideas from being communicated. If richness prevents your ideas from being transmitted outright, then what's the point? If the author had used Markdown their idea would have been better communicated, but I guess that also would have contradicted it.
Opened this site to find the readable text was squashed into the middle maybe 10% of my screen, as much as markdown can be annoying - websites that refuse to use a reasonable portion of the browser width for readable content annoying me far more.
This doesn't back the hypothesis that there are applications (cough opportunities) held back by markdown's deferral of styling.
Markdown's chief feature is to be usable without tooling when writing, so more content is generated in the first place. So it extends the rich/cost graph to the left.
Because markdown is easily and often parsed, it operates as a data source from the get-go, mostly achieving the separation of concerns needed to scale to the right.
What are the pain or price points that will change with adopting this new technology?
(Is Swift-docc really the comparable? It seems to show what this is hopefully not: a subset dialect of markdown struggling with volatile, unusable hash links, no real extensibility or inter-op, tethered to BigCo's mission.)
(The curse of curses: they provoke negativity.)
Markdown's chief feature is to be usable without tooling when writing, so more content is generated in the first place. So it extends the rich/cost graph to the left.
Because markdown is easily and often parsed, it operates as a data source from the get-go, mostly achieving the separation of concerns needed to scale to the right.
What are the pain or price points that will change with adopting this new technology?
(Is Swift-docc really the comparable? It seems to show what this is hopefully not: a subset dialect of markdown struggling with volatile, unusable hash links, no real extensibility or inter-op, tethered to BigCo's mission.)
(The curse of curses: they provoke negativity.)
This would be a much better article if two things changed: One, skip the scroll gimmick. It's a waste of time and space (and that has been discussed enough)
Two, give us examples that live in that supposed wasteland. Without those, it looks like you're building a technology in the abstract. And, don't get me wrong, it's cool tech. It so tickles my sense of "fun engineering challenge, great way to express structure". But I've long learned that means it's also very likely in the "overengineered" corner.
I share your belief that there's a "there" there. (I'm on my umpteenth iteration of my own personal markdown, so I would ;) I think it'd be helpful to crystallize that into more concrete uses.
Two, give us examples that live in that supposed wasteland. Without those, it looks like you're building a technology in the abstract. And, don't get me wrong, it's cool tech. It so tickles my sense of "fun engineering challenge, great way to express structure". But I've long learned that means it's also very likely in the "overengineered" corner.
I share your belief that there's a "there" there. (I'm on my umpteenth iteration of my own personal markdown, so I would ;) I think it'd be helpful to crystallize that into more concrete uses.
This entire argument is weird. My website is relatively rich in content, in different contexts, including (now out of date/deprecated) interactive tutorials. Every single thing on my website is statically generated from Markdown.
Nothing about richness or leanness is implied or enforced by using Markdown for text, it's about everything else around it. On a statically generated page, you do it in Javascript, and render client-side if needed w/ data prepopulated in static objects. The only thing you can't do with a static page that ingests text as RST or Markdown or any other markup language, is something that requires dynamism with a backend database.
This is trying to blame Markdown and statically generated sites for leanness, but minimalism is a stylistic aesthetic choice people made that was a trend for awhile, it's not a requirement of the technology. The technology is just a tool.
Nothing about richness or leanness is implied or enforced by using Markdown for text, it's about everything else around it. On a statically generated page, you do it in Javascript, and render client-side if needed w/ data prepopulated in static objects. The only thing you can't do with a static page that ingests text as RST or Markdown or any other markup language, is something that requires dynamism with a backend database.
This is trying to blame Markdown and statically generated sites for leanness, but minimalism is a stylistic aesthetic choice people made that was a trend for awhile, it's not a requirement of the technology. The technology is just a tool.
From TFA:
> The impact of Markdown becomes clear if we plot a random sample of content websites. (Disclaimer: the data is made-up, based on my perception of the state of the web)
Perhaps the author's thesis is wrong.
> The impact of Markdown becomes clear if we plot a random sample of content websites. (Disclaimer: the data is made-up, based on my perception of the state of the web)
Perhaps the author's thesis is wrong.
The text graying out and scrolling effect leads to overlaps for me. Firefox 133.
https://i.ibb.co/NryLFgJ/codehike-overlap.jpg
https://i.ibb.co/NryLFgJ/codehike-overlap.jpg
“I have created a tool, and I’m imagining that it’s very important. Just look at this data I made up!” What a joke.
I think the author forgot to think about the content and got all invested in the display of their site. Should have just used markdown and spent the saved time looking for actual real data.
I think the author forgot to think about the content and got all invested in the display of their site. Should have just used markdown and spent the saved time looking for actual real data.
> This jump in cost disrupts the trade-off between richness and effort. For content with a sweet spot just beyond Markdown’s limits, the additional effort often seems too high for the small gain in richness, leading to a preference for staying with Markdown and sacrificing richness.
Why is asciidoc not more popular? It seems to support more than markdown and seems straightforward.
Why is asciidoc not more popular? It seems to support more than markdown and seems straightforward.
asciidoc, restructured text, and there are several others tools that support some more features.
> Imagine how many ideas are held back because their authors don’t have the right tools to express them.
IMHO article would be much better while not exploring new ideas and use simple text and web-native controls instead of inconvenient accessibility-wise poor UI/UX.
P.S. Print preview is hilariously bad.
IMHO article would be much better while not exploring new ideas and use simple text and web-native controls instead of inconvenient accessibility-wise poor UI/UX.
P.S. Print preview is hilariously bad.
Almost all of the blog posts and articles I write nowadays are in Markdown, and it sure is painful sometimes when you need formatting that you just need a liiiitle bit of tweaking to get right.
My solution is to fork the markdown tool I use to add my own tweaks. Some of the changes I added are:
- Vertical padding: Typically, `---` and `*` get converted to `<hr>` tags. I use `*` for `<hr class="small">` that has different padding top/bottom.
- Code examples with syntax highlighting.
- Block quotes with class names: `> {.warning}`
- Headers and table rows with support for setting a specific anchor ID: `# Header {#myId}`
- `<img>` tags with CSS URL matching to apply certain styles. For example, match `<img>` tags URLs ending with `#screenshot` will have drop shadow.
My solution is to fork the markdown tool I use to add my own tweaks. Some of the changes I added are:
- Vertical padding: Typically, `---` and `*` get converted to `<hr>` tags. I use `*` for `<hr class="small">` that has different padding top/bottom.
- Code examples with syntax highlighting.
- Block quotes with class names: `> {.warning}`
- Headers and table rows with support for setting a specific anchor ID: `# Header {#myId}`
- `<img>` tags with CSS URL matching to apply certain styles. For example, match `<img>` tags URLs ending with `#screenshot` will have drop shadow.
The first example website given here is described "just text with minimal styling." It's not just text though, it's hypertext? Since when did everyone lose sight of what hypertext is.
Is there anything more going on here than "use the right tool for the job?"
I really like the format. The problem with slideshows is you either have to scroll back and forth or click on the next page buttons. This page fixes both of them. Although I can see how the fading out of the text is a bit annoying.
Also is anyone building websites with markdown? I thought it was just a tool to format notes and blog posts. And even then you can insert HTML in it.
Also is anyone building websites with markdown? I thought it was just a tool to format notes and blog posts. And even then you can insert HTML in it.
We already have a markup language capable of this. It's called HTML.
> Disclaimer: the data is made-up, based on my perception of the state of the web
The problem is made-up, too, based on the author’s (incorrect) perception of markdown.
You can start dropping in as much or as little HTML as you want.
The problem is made-up, too, based on the author’s (incorrect) perception of markdown.
You can start dropping in as much or as little HTML as you want.
A fun example that shows how interactivity isn’t necessarily the best thing to judge richness by is Janet for Mortals which is 100% html and likely markdown but also embeds the Janet interpreter so you can use the language as you learn it.
https://janet.guide/
https://janet.guide/
I used to feel bad about trying to shoehorn markdown into places it clearly wasn’t suited, but Quarto put an end to those concerns. It makes damn near anything possible thanks to Pandoc, and sure beats the mish-mash of various single-purpose tooling I used to use for presentations, memoranda, static site generation, documentation, etc.
I think markdown is poorly designed, especially in terms of ease of parsing (human AND machine!)
I've written my own markup language, I'd love ANYONE'S feedback, either good or bad
https://lua.civboot.org#Package_cxt
I've written my own markup language, I'd love ANYONE'S feedback, either good or bad
https://lua.civboot.org#Package_cxt
Why did you make the decisions you did? My very first impression was “this looks different from Markdown for the sake of being different”. You say yours is easier to parse. Can you give some examples of when that might be try? Things like [*bold text] seem like they’d be harder to parse.
(It’s hard to communicate tone here. My intent above was to sound curious, not dismissive.)
(It’s hard to communicate tone here. My intent above was to sound curious, not dismissive.)
The bulk parser only needs to read a single character and only needs to care about two characters (brackets). The sub parser then looks for either {...} or a single character.
Markdown requires all sorts of complexity and it's nearly undecideable. Before CommonMark there wasn't even a spec and many things were largely ambiguous.
Also, tables and other structured data in markdown are almost entirely hacks
Markdown requires all sorts of complexity and it's nearly undecideable. Before CommonMark there wasn't even a spec and many things were largely ambiguous.
Also, tables and other structured data in markdown are almost entirely hacks
Interesting idea, but it seems to be tied to react, which IMO is too far in the other direction.
This format—with each paragraph fading as you scroll, and large changing images alongside—is borderline unreadable.
Somewhat ironic in a blog post that (I think) is about tradeoffs between text and formatting.
Somewhat ironic in a blog post that (I think) is about tradeoffs between text and formatting.
All that work to animate the little bits of data on the canvas, but greying the text was so irritating I closed the page. You don't realize how often your eyes jump back to previous sections until that ability is taken away from you.
It seems like they wanted to make sure the reader knew which paragraph corresponded to the current version of the image/plot. Maybe they could've gotten the effect they were after by setting a border or background on the presently relevant paragraphs.
It seems like they wanted to make sure the reader knew which paragraph corresponded to the current version of the image/plot. Maybe they could've gotten the effect they were after by setting a border or background on the presently relevant paragraphs.
Or even using the top as a kind of progress marker so you know where you are (or just reading from the middle of the page) only for the text to turn grey as you read it.
It is so unnecessary and distracting. I quit reading after the first scroll as my eyes were pulled away from the text.
That's why I hate things like auto-rotating image/news carosels or Windows "live tiles". Having them manually triggered is fine but a) I may be half-way through reading a headline; and b) if I'm reading something off to the side it draws my eye for a moment, disrupting my workflow.
On top of that, the content itself—a spectrum of lean to rich—isn't all that informative, especially compared to its solemn presentation as the result of some kind of deep meditation.
Also:
> Imagine how many ideas are held back because their authors don’t have the right tools to express them
Ironic when only the first paragraph is shown when JS is disabled.
> Imagine how many ideas are held back because their authors don’t have the right tools to express them
Ironic when only the first paragraph is shown when JS is disabled.
I switched to Reader Mode in the hope of getting something more usable, but the screenshots of the Nat Friedman and Tailwind websites take up a bunch of space between every paragraph of content, making even Reader Mode awkward to navigate.
This. This looks fine as a some sort of demo and when opened on 14" macbook but on 27" monitor this is just torture.
This comment made me curious, but I still wasn't ready for how comically bad it is. On my large screen monitor, that single paragraph looks infuriatingly bad. It's so much wasted space that it detracts from anything else.
I initially closed the tab immediately, as I assumed that the greyed-out text was indicative of a paywall.
It's a slideshow. I actually kinda like it.
Even in slideshow format there's no need for this distracting nonsense. Something like https://idlewords.com/talks/our_comrade_the_electron.htm is perfectly fine.
I actually find that much more distracting since you can see the images ahead of time, but to each their own.
I am not sure Markdown is a curse because of the gap that it creates in the chart. But I agree with one thing: we do need to explore interesting DSLs for producing beautiful documents.
[deleted]
What's an example of a website or feature which needs just a little bit more "richness" than a static website with formatted text and links and images?
Any page that needs a table of contents with links to the sections.
Markdown supports TOC. Some flavors at least.
Unfortunately not the flavor I am using. Or at least it didn't when I got mad enough to switch to restructured text and a more complex build process. Where I've seen a TOC in markdown it was far too much manual effort to maintain the TOC and they tore it out some years back - but maybe better implementations exist today
I fill your pain. For example bitbucket has a total garbage instead of proper markdown renderer. No TOC, no stable header links, no navigation to anchors on first page visit, no image scaling.
But if you control documentation render process there is a number of feature-rich renderers like pandoc, mkdocs and others.
But if you control documentation render process there is a number of feature-rich renderers like pandoc, mkdocs and others.
I used RUNOFF back in the 1970s. I used it for writing papers. Things haven't evolved much beyond it.
Check out this format: https://marko.blog
The fact that this website decided to "fade out" the paragraph at the scrolling level where I usually read is infuriating.
> Imagine how many ideas are held back because their authors don’t have the right tools to express them.
Sir, you've reinvented text with images.
Sir, you've reinvented text with images.
[deleted]
Meh. An overengineered article about markdown. I stopped reading after: "Disclaimer: the data is made-up, based on my perception of the state of the web".
MD is a tool, just as any other tool after becoming familiar with it, you know in advance if it's going to serve you well or not and of its potential limitations.
I keep all valuable personal notes on a local Hugo which is basically all markdown and I wouldn't have this if I had to write things down myself in any other format. So no, is not a curse at all but a timer saver for me it is.
MD is a tool, just as any other tool after becoming familiar with it, you know in advance if it's going to serve you well or not and of its potential limitations.
I keep all valuable personal notes on a local Hugo which is basically all markdown and I wouldn't have this if I had to write things down myself in any other format. So no, is not a curse at all but a timer saver for me it is.
Non-related, but this is the first time I actually like animations that happen while scrolling. I think it has something to do with the fact that I still have control over the scroll on the right.
Yes, this one doesn't hijack the scroll. It just reacts to it, by changing the text formatting.
I still didn't like it. But it's undeniably much better than the usual way people animate their sites.
I still didn't like it. But it's undeniably much better than the usual way people animate their sites.
Having tried out CodeHike, there are a number of configurations or situations where you can get into scrolling and alignment issues
I'd much rather see each individual graph as a picture so I can compare.
There's a special circle of hell for places who make "plot-like" illustrations that are supposed to look like data visualisations but are just graphics. It's extremely deceptive.
TFA has a bunch of things which look like plots of richness vs cost but are actually just what a statistician would call "totally made-up bullshit"
TFA has a bunch of things which look like plots of richness vs cost but are actually just what a statistician would call "totally made-up bullshit"
"There is a relation, and it should look like this" is a very common way for people to express themselves.
Your way would ban all the engineerings and most of physics from being created.
Your way would ban all the engineerings and most of physics from being created.
What you're talking about is a sketch, which is totally fine. What this website produces is a thing that is very clearly a facsimile of a plot. It literally has made an attempt to produce points of different sizes etc, to look like a bubble plot but it's not. It's just made up.
I think GP is saying that just lines on the same plot would have been less deceptive, whereas the plot that is actually there has fake data points. Readers are used to the former being purely imaginative, whereas the latter almost always means there's real measurement involved.
I love how this is formatted - reading it in those little blocks with an image to make it more clear. It is a joy to read.
The actual point itself is somewhat interesting too. "curse" is a strong word though.
The actual point itself is somewhat interesting too. "curse" is a strong word though.
I hate that I'm forced to scroll just to be able to read something that is already in the screen, but each to its own.
the chart is flashy, but pretty meaningless, there is zero value from it and everything looks overcomplicated.
the chart is flashy, but pretty meaningless, there is zero value from it and everything looks overcomplicated.
Funny. For me, it is horrible user experience. Don't decide for me. Let me read what's already on screen. I hate scroll jacking of any type.
This isn't scroll jacking, any more than it's "scroll jacking" when there's a header or menu sidebar which doesn't move with the text. Scroll jacking means something specific, like the style which was introduced by NYT and has been imitated badly ever since, where sometimes scrolling triggers animations and then the text gets the scroll back.
Here, the main text moves up and down when you scroll, and there's an illustration on the side which changes accordingly. I'm seeing mixed opinions about that stylistic choice here, I don't have a strong one myself.
Just that it isn't scroll jacking. It's some other thing.
Here, the main text moves up and down when you scroll, and there's an illustration on the side which changes accordingly. I'm seeing mixed opinions about that stylistic choice here, I don't have a strong one myself.
Just that it isn't scroll jacking. It's some other thing.