Skip to content

Commit ded084d

Browse files
pomberpomber
committed
The curse of markdown draft
1 parent dd36e54 commit ded084d

File tree

10 files changed

+659
-86
lines changed

10 files changed

+659
-86
lines changed

‎.vscode/settings.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
{
22
"explorer.fileNesting.enabled": true,
33
"explorer.fileNesting.patterns": {
4-
"*.0.mdx": "${capture}.*"
4+
"*.0.mdx": "${capture}.*",
5+
"*.mdx": "${capture}.*"
56
},
67
"explorer.fileNesting.expand": false
78
}

‎apps/web/app/layout.tsx

+6-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,12 @@ import { Metadata } from "next"
1414

1515
export default function Layout({ children }: { children: ReactNode }) {
1616
return (
17-
<html lang="en" className={inter.className} suppressHydrationWarning>
17+
<html
18+
lang="en"
19+
className={`${inter.className} snap-y`}
20+
suppressHydrationWarning
21+
>
22+
{/* <script src="https://unpkg.com/intersection-observer-debugger"></script> */}
1823
<body suppressHydrationWarning>
1924
<RootProvider>
2025
<NavBar version={ch.version} />

‎apps/web/content/blog/the-curse-of-markdown.mdx

+88-35
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,115 @@
11
---
22
title: The Curse of Markdown
3-
description: And the website wasteland
4-
date: 2024-10-12
3+
description: And the content website wasteland
4+
date: 2024-11-21
55
authors: [pomber]
66
draft: true
77
---
88

9-
import { Chart } from "./the-curse-of-markdown"
9+
import { Layout, RainbowList } from "./the-curse-of-markdown"
1010

11-
Markdown is so good that it can hurt you.
11+
<Layout>
1212

13-
first
13+
## !!steps lean
1414

15-
<Chart name="first" />
15+
### The Lean-Rich Spectrum
1616

17-
In a world without Markdown,
17+
We can think of content websites on a scale from lean to rich.
1818

19-
<Chart name="second" />
19+
A good example of a **lean content website** is [nat.org](https://nat.org), it's just text with minimal styling.
2020

21-
chapters:s
21+
Making nat.org richer—by adding interactive elements or a fancy layout—won't add much value to its purpose, only distraction from the content.
2222

23-
- introducing richness vs ax
24-
- pre-markdown tradeoffs
25-
- enter markdown
26-
- the tradeoff wall
27-
- enter mdx
28-
- enter rsc
29-
- the content presentation gap
30-
- enter code hike
23+
## !!steps rich
3124

32-
Tradeoffs: https://youtu.be/zqhE-CepH2g?si=7iYgDUjAhJNVmYJN&t=446
25+
A great example of a **rich content website** is the [Tailwind CSS](https://tailwindcss.com) landing page.
3326

34-
- technical cost vs product benefit
27+
It uses interactive examples, animations, and engaging visuals to highlight how TailwindCSS works and what it can do.
3528

36-
examples of websites that mdx allow:
29+
Making the site leaner—by removing these rich elements—would make it harder for visitors to understand what TailwindCSS offers.
3730

38-
- interactive blogs
39-
- interactive docs
31+
## !!steps rich
4032

41-
---
33+
Along the spectrum from lean to rich, we can find websites like:
4234

43-
it doesnt mean that there aren't websites in this zone. but they pay a high price, either because they have resources to do so, or because they care a lot about the product.
35+
<RainbowList>
4436

45-
Examples are:
37+
- Static blogs
38+
- Documentation websites
39+
- Visual essays
40+
- Explorable explanations
41+
- Interactive tutorials
4642

47-
- stripe
48-
- swiftui
43+
</RainbowList>
4944

50-
---
45+
## !!steps richness
5146

52-
specific tools like:
47+
### The Content-Richness Sweet Spot
5348

54-
- swiftui docc
55-
- tutorialkit
56-
- codehike before v1
49+
For each piece of content, there is a sweet spot of richness. The perfect richness level depends on how complex the content is.
5750

58-
---
51+
Not enough richness makes it harder for the author to express their ideas and for the reader to understand them.
52+
53+
Too much richness requires extra effort from the author and leads to more distractions for the reader.
54+
55+
## !!steps effort
56+
57+
### The Cost of Richness
58+
59+
Making a website richer requires more effort.
60+
61+
**In a world without Markdown** or any markup language other than HTML, **the cost of building a website grows linearly with its richness**. A slightly richer website requires a slightly higher effort to build.
62+
63+
## !!steps markdown
64+
65+
If we add Markdown back into the equation, the cost of building lean websites becomes much lower. Markdown’s simplicity and tooling make it almost effortless to create text-focused sites like blogs or documentation.
66+
67+
Tools like MDX, Markdoc, and plugins extend the range of websites that can be built with Markdown, allowing for richer websites with some extra effort.
68+
69+
## !!steps wall
70+
71+
### The Tradeoff Wall
72+
73+
But Markdown has its limits. Beyond a certain level, Markdown stops being helpful and the cost of building remains as high as before.
74+
75+
**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.
76+
77+
## !!steps population
78+
79+
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)
80+
81+
Most websites are on the lean side. A few outliers sit just beyond Markdown’s limits. At the richer end we see a decent share of websites, where the tradeoff between effort and richness starts to make sense again.
82+
83+
## !!steps wasteland
84+
85+
### The Website Wasteland
86+
87+
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.
88+
89+
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.
90+
91+
## !!steps repopulating
92+
93+
### Repopulating the Wasteland
94+
95+
To bring more websites into this space, we need tools that lower the effort required to create richer content.
96+
97+
Some new tools address this by focusing on **specific content-presentation types**, like [Swift-DocC](https://github.com/swiftlang/swift-docc), that compiles Swift into rich developer documentation, or [TutorialKit](https://github.com/stackblitz/tutorialkit) a tool for creating interactive tutorials.
98+
99+
## !!steps repopulating2
100+
101+
While those tools are great, they target very specific types of websites. This was also the case with Code Hike before version 1.0—a tool I built that was limited to a set of layouts without much flexibility.
102+
103+
But I believe that more **general-purpose tools** are possible. Tools that bring the trade-off between richness and effort back into balance.
104+
105+
That's my vision for Code Hike v1, and the idea behind [fine-grained markdown](/blog/fine-grained-markdown).
106+
107+
## !!steps why
108+
109+
### Why does it matter?
110+
111+
Imagine how many ideas are held back because their authors don’t have the right tools to express them.
59112

60-
The curse:
113+
By lowering the barriers to richer content websites, we can unlock the web’s unmatched potential to support the full spectrum of richness, allowing every idea to be expressed in the most fitting way for its depth and complexity.
61114

62-
More often than not, the answer is to stick with Markdown and compromise on the complexity of the site. It’s easier, it’s familiar, and it lets you avoid the cost of adopting more complicated solutions. And that’s where the curse lies: Markdown is so effective at the simple stuff that we often don't even try to build things that are slightly more ambitious. The result is a gap in the spectrum of static sites — a whole category of rich, content-driven sites that never get built because the trade-off doesn’t seem worth it.
115+
</Layout>

0 commit comments

Comments
 (0)