The Curse of Markdown(codehike.org) |
The Curse of Markdown(codehike.org) |
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
You can verify the content with : curl https://www.tducret.com/pure-markdown/
So writing or using someone else's custom element is pretty much your only option here.
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.
More context:
https://github.blog/engineering/user-experience/a-formal-spe...
I won't rehash it here, it's been mentioned before both here and in Coding Horror (Atwood's blog)
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.
it's a space that broke <A /> because they're too useful and needed a broken react special version.
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.
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.
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.
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.
It has nothing to do with complicated.
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.
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.
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.
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.)
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.
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.
> 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.
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.
Why is asciidoc not more popular? It seems to support more than markdown and seems straightforward.
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.
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.
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.
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.
I've written my own markup language, I'd love ANYONE'S feedback, either good or bad
(It’s hard to communicate tone here. My intent above was to sound curious, not dismissive.)
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
Somewhat ironic in a blog post that (I think) is about tradeoffs between text and formatting.
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.
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:
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.
> 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.
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.
This is a really stupid take.
This is exactly why I ditched WYSIWYG long before I knew how to code.
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.
> 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.
Sir, you've reinvented text with images.
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.
I still didn't like it. But it's undeniably much better than the usual way people animate their sites.
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"
Your way would ban all the engineerings and most of physics from being created.
The actual point itself is somewhat interesting too. "curse" is a strong word though.
the chart is flashy, but pretty meaningless, there is zero value from it and everything looks overcomplicated.
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.
From a quick search only "mainstream social media" which offers native bold functionality is WhatsApp. And it uses markdown-style.
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.
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
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.
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.
Though for what its worth, "no official agreed upon spec" didn't stop browsers before haha
But if you control documentation render process there is a number of feature-rich renderers like pandoc, mkdocs and others.
