Thoughts on Markdown | Hacker News Reader

Thoughts on Markdown

smashingmagazine.com

66 pointssanqui14 comments

It's a real shame that Markdown beat out AsciiDoc(tor). The original AsciiDoc project was even released before Markdown. But compared to Markdown, Asciidoctor makes it just as easy to write simple formatted text; makes it far easier to write complicated markup such as definition lists and tables; supports common article-authoring features like a table of contents, footnotes, and inclusion of other documents; supports the use of simple variables that get expanded when the document is rendered; supports anchors and CSS-style classes; provides an API for user-authored extensions (in Ruby, for Asciidoctor) to customize document processing; and renders to an intermediate format not coupled to any one output format.

I cringe whenever I have to write markdown. It's such a bad format, and it's a shame that people tried to keep bolting on additional features it wasn't meant to support instead of just picking a better option. I wonder if John Gruber even knew about AsciiDoc when he started work on Markdown, and if he would have gone to the trouble if he had.

I kind of agree, although I find them useful for different things. Markdown is terrific for casual text entry that needs a little bit of markup—being able to add italics or bold or a formatted link inside of comments or discussions is really handy, and it works well in chat clients and GitHub and things like that.

Where Markdown falls down is when people try to apply it to larger, more formal documents that need specific formatting choices: footnotes, specific list layouts, table line breaks, etc. Once you get up to trying to publish a more complicated document, you find the edges of Markdown pretty quickly. I would say "right tool for the right job", but the problem is that once devs get used to one format, they don't want to learn another.

Previous discussion from earlier today¹ with a hefty bunch of comments.

¹ https://news.ycombinator.com/item?id=30395130

These are good thoughts. The crux I'm taking away is two-fold: Markdown is great for the developer community, but not the broader authorship community; and the fragmentation of Markdown makes for a rough experience for anyone maintaining Markdown-based tools.

I decided to use Markdown for the first implementation of Haven[1]'s editor but I'm definitely keeping my eye on some of these newer block-based systems. There was a Joel-on-software post last month advocating for something similar[2].

One advantage I keep thinking about (but probably over-value) is graceful degradation without Javascript. You can still write Markdown in a `textarea` and submit it in a form. Is there a similar fall-back for these modern editing systems?

[1]: https://havenweb.org [2]: https://www.joelonsoftware.com/2022/01/27/making-the-web-bet...

I wrote a blogpost on "6 Things Markdown Got Wrong" last year and John Gruber actually weighed in! https://www.swyx.io/markdown-mistakes

Things should be as simple as possible, but no simpler.

MD is definitely an example of simpler than possible.

I've been exclusively using Markdown for all docs for several years which I've found to be the most productive format for writing docs. My preferred setup now being to use VS Code with a browser running a local instance of https://vitepress.vuejs.org which instantly live reloads content on each save and renders our custom server components exactly as it looks when published.

Its biggest benefit is its extensibility which lets you embed interactive Vue Components directly in the docs, which we've made liberal usage of in our latest product release with tabbed components & online project creator embedded directly in the release notes, e.g:

https://docs.servicestack.net/releases/v6#todos-mvc

A lighter weight extensibility option is to extend it [1] with custom block-level custom containers using markdown-it-container [2] which lets you create custom markup like this:

::: nuget `<PackageReference Include="ServiceStack.OrmLite.PostgreSQL" Version="6.*" />` :::

::: sh x mix postgres :::

Which gets rendered into custom copy widgets as seen in:

https://docs.servicestack.net/ormlite/installation

Source:

https://raw.githubusercontent.com/ServiceStack/docs/master/d...

Markdown all text things!

Basically if it needs to capture text content, I'll look for the Markdown version if it exists, which extends into my preferred TODO App: https://notable.app - a beautiful little App that manages a static directory of *.md files. My first TODOs replacement of using notepad.exe that's stuck.

[1] https://vitepress.vuejs.org/guide/markdown.html#advanced-con...

[2] https://github.com/markdown-it/markdown-it-container

If we are going to design something new, we should probably start with the WYSYWIG editor and only then design the actual data format.

If we want machine readable data we should think first about how it will be authored. Maybe our new format has Excel style tables, and Mustache templates that can read them, so that we can just drop in a table view widget in the editor and customize it, filter it, let users sort it, etc.

Maybe our tables have a type UUID for identifying what the table layout is.

Markdown is mostly a failure. Yes, it's more convenient than writing your README in docx or txt, but if you want to do anything with it off the narrow beaten path, you'll inevitably have to extend it or give up.

For example, let's say you want something that's not supported by Markdown's syntax, such as dictionary lists, but you want to be able to use Markdown's text formatting syntax with it:

```markdown

<dl>

  <dt>*foo*</dt>

</dl>

```

Most Markdown parsers don't apply Markdown parsing of text nodes within HTML elements. This is why the argument that Markdown supports HTML doesn't work, because it literally doesn't work for why we are using Markdown in the first place... which is to avoid the verbosity of HTML.

This kind of thing really bugs me. No matter what, whenever I've tried using Markdown as a tool for constructing webpages rather than snippets/comments within pages, I end up having to write a custom AST transformer to either get the parser to produce the right output or to prevent it from adding <p> tags around block elements that shouldn't have them in the first place.

Maybe a formal standardization could be the first step to actually addressing such issues, but it's questionable whether it's worth the bother.

> Maybe a formal standardization

In practice, that's what pandoc is (and it includes definition lists as extensions: https://pandoc.org/MANUAL.html#definition-lists )

You also have commonmark (an actual standardization) from the same author: https://commonmark.org/ (but DLs are not part of commonmark yet)

> Yes, it's more convenient than writing your README in docx or txt, but if you want to do anything with it off the narrow beaten path, you'll inevitably have to extend it or give up.

This is true for everything that people actually use. What you just quoted, a "<dl>" tag, is a writing concept that I, and I think most people, have never heard of and have never used in written documents. Maybe that should change, but that's kinda how it is...

AsciiDoc supports definition lists out of the box and I use it all of the time. Instead we see authors using headings above list which is technically incorrect, block quotes for admonitions, and many other poor uses of markup. The same community of devs that laughs at WYSIWYG editors and using bold tags and breaks instead of headings and paragraphs are abusing markdown; like pressing a B for bold, they look at what tools Markdown gives them visually paying no mind to the output markup.

I don’t want markdown to handle html, personally, because it makes it unfit for any use outside of a professional setting.

For community wiki situations you do not want anything that is even accidentally Turing complete because you will end up with malicious content. In a work setting you are putting your job in danger if you do something like this, so there is mutually assured destruction. No such thing with random internet strangers.

It’s also just a crutch. Thinking you can reach for HTML means you don’t find inspiration to solve problems like having anchors on headings

Markdown was not designed to make an end user's life easier. It was designed to make it easier for somebody to write the most generic document imaginable. It's part of the general disease of developers creating solutions solely for developers, at the expense of anyone who isn't a developer.

Reply on news.ycombinator.com