Markdown should be readble without knowing Markdown

Written by Asanka Herath on April 5, 2022 | #Tools #Engineering

Markdown started out as a way to write text files that could also be machine parsed and rendered into a higher fidelity format.

To quote from the Philosophy:

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

This particular aspect of the format wasn’t maintained very well. Immediately following the “Philosophy” section is “Inline HTML” which contradicts the “without looking like it’s been marked up” requirement.

The ease of writing goal was met head on. So much so that it is now the de-facto format for writing documentation that documents in general that has any kind of formatting at all. This blog post is also based on a markdown document.

People – of course – need more features. And features there were many. The “Variants” section of the Wikipedia page on Markdown touches upon some of the popular syntaxes that exist now.

On pet-peeve I have is that these new features don’t even try to adhere to the minimum markup philosophy. And hence just introduce HTML tags – or worse HTML-like but not HTML tags – into the format. Someone who’s not familiar with Markdown syntax – or for that matter whatever dialect you are using for some document – shouldn’t be thrown off by the additional markup.

Better Definition Lists?

I really don’t like the “Definition List” syntax. This feature isn’t in the original Markdown syntax, but is a part of many extended syntaxes. It looks like this:

Some term
: The definition of the term. Long lines can be
  broken down while preserving the indent. But
  the first character can't be ':' or it will become
  *another* definition.

See, it’s easy to see the : as some misplaced punctuation rather than markup when just reading the text. Instead how about maybe this?

Some term:
  The definition starts here. Long lines can be
  broken down like this.
    
  Maybe continue the definition here.

It looks more like a definition in a regular text file.

Better Code Blocks?

The original syntax for code blocks is to just add extra space in the middle, like so:


This is normal text.

    function ThisIsACodeBlock() {
    }

More normal text.

See, if you saw this in a text file, your eyes would easily follow the context switch. Instead, the most popular markdown formats use the following kind of markup:


This is normal text.

```
function ThisIsACodeBlock() {
}
```

More normal text.

See how the markup is in the way? There’s a reason for the special markup; it allows specification of additional attributes like the underlying language that the code block is in.

Instead, how about something like this?


This is normal text.

javascript code:

    function ThisIsACodeBlock() {
    }

More normal text.

It re-uses the some text: syntax that’s used for specifying links.

Better admonitions?

Admonitions aren’t a feature of regular Markdown. It’s available as an extension in select Markdown processors. The syntax is a little horrendous:

!!! type "optional explicit title within double quotes"
    Any number of other indented markdown elements.

    This is the second paragraph.

Okay the exclamation points kind of hints at what this is supposed to mean. But how about this?

NOTE: Optional explicit title
    Paragraph that contains extra details about the note.
    
    This is the second paragraph.

It’s obvious from looking at the plain text what this is supposed to be; no need to go look at the documentation for your Markdown dialect to figure out what on earth !!! title is supposed to be.

Better collapsed sections?

Okay, so this one is specific to GitHub Flavored Markdown, and it’s terrible. It comes down to the genre of just writing HTML:

<details><summary>CLICK ME</summary>
<p>

#### We can hide anything, even code!

    ```ruby
    puts "Hello World"
    ```

</p>
</details>

WTF? You might as well write the thing in HTML and call it a day. Maybe if they could’ve gone with something like:


Summary goes here.

Details:
  Details go here. and yes you can use fenced code blocks.
  
      Like this.
      
  Or the ugly way:
  
  ```
  Like this.
  ```

Once again it re-uses the some text: syntax, and it could probably use either details or Details. Either way, you don’t need to understand the markup to see where this is going.

← → Top