
Things Markdown got wrong - swyx
https://www.swyx.io/writing/markdown-mistakes/
======
combatentropy
I wish that markdown formatted bold and italics like this:

    
    
      _italic_
    
      *bold*
    

instead of:

    
    
      _italic_
    
      *italic*
    
      __bold__
    
      **bold**
    

because stars around a word make it look like it's glowing, sort of like bold
does, and underlining a word means to make it italic. Does no one remember
this?

In English class, before computers, our teacher told us that certain words are
always underlined: book titles, ship names, etc.

In Typing class, our teacher told us that if you submitted a typewritten
manuscript to a publisher, what you underlined with your typewriter would be
converted to italics in a typeset book. Underlining meant italics. And sure
enough, nowadays when everyone has a computer instead of a typewriter, and can
make real italics, they tell us that book titles, ship names, etc., ought to
be in italics (the same things that my teacher used to tell us should be
underlined) [https://www.purchase.edu/editorial-style-guide/general-
style...](https://www.purchase.edu/editorial-style-guide/general-style-
preferences/italics-and-underlining/)

I get kind of why Gruber did it his way. He was caught up in the Semantic Web,
where you don't use <i> and <b>, you use <em> and <strong>, and <strong> means
<em> only more so. So by that logic

    
    
      *this*
    

is emphatic, and

    
    
      **this**
    

is strongly emphatic.

~~~
samatman
I'm enamored of the org-mode textual formatting convention: •bold︎•, /italic/,
_underline_, =literal=, and ~strikethrough~. Although `literal` a la Markdown
is arguably better, I prefer the other choices.

Especially because org-mode lets you italicize //Face/Off// by adding more
slashes, and so on for the others, like ==e = mc^2==.

Incidentally, I have no idea how you're typing literal asterisks, I gave up
and am kinda jealous.

~~~
adrusi
I really dislike /italic/. Relative to the slashes, the letters look like
they're skewed in the wrong direction. Surely it should be \italic\\. If
unifying underlines and italics doesn't suit you.

~~~
ScottFree
Is this a localization thing? In this image here[0], the italicized word
clearly leans to the right.

Funny thing happened when I tried to type that out: typing /italics/ caused
libre office to automatically italicize the word.

[0]: [https://imgur.com/cq7BMex](https://imgur.com/cq7BMex)

~~~
adrusi
When I read /italic/ or \italic\, I end up mentally transforming the text so
that the slashes are vertical lines. When you do that with forward slashes,
you get text with a negative slope (the wrong way).

Demonstration:
[https://codepen.io/adrusi/full/poJXRgy](https://codepen.io/adrusi/full/poJXRgy)

~~~
ScottFree
Huh. That's pretty damned interesting. Thanks for explaining!

------
holman
> I'm not sure who invented [fenced code blocks], but I definitely know that
> it is widely used because GitHub Flavored Markdown made it so and I am
> grateful for that.

I’m pretty sure Vicent Martí (@vmg) was the originator of them. I remember we
spent a number of weeks internally at GitHub debating the syntax, since no one
really fell in love with any of the proposals for various reasons. Eventually
the triple tick won out and that’s worked out fairly well, I think.

~~~
rapsey
Man I hate those ticks. I have no idea what arcane key combination on my
keyboard I need to do to get them. Maybe it's easier on a US keyboard.

~~~
chrizel
It’s very easy on the US keyboard: the key for ticks is under the escape key,
no shift needed, just hit this single key.

I’m German myself, but I use the US keyboard layout for more than 15 years
now, because it is so much easier to type things like this... especially in
tech. (And also keys for [, ], { and } are much better placed in the US
layout)

~~~
loeg
Do most Germans use QWERTZ?

~~~
chrizel
Yes, most people learn and use QWERTZ. In your typical electronics store, you
will only find QWERTZ keyboards and notebooks. If you want QWERTY, you have
only one option, you have to buy it on the internet. But even on the internet
the typical Logitech keyboard for example is hard to find in US-QWERTY in
Germany/Europe, because most merchants don‘t have them on stock. In the past,
I‘ve even imported US keyboards from the US, because they were and are hard to
find here.

It gets even more difficult for notebooks: Any notebook you can buy here in
Germany has QWERTZ. Want a notebook with US layout, because you are a
developer? Your only options are BTO options from Apple or Lenovo. But even
there, you have to be cautious: Dell for example will sell you „English“
keyboard layout notebooks as BTO option, but you won‘t get the real US layout
(with a wide return and wide left shift key), but some kind of „International
English“ ISO layout with a tall return key and a short left shift key...
Lenovo has an „English“ option and thankfully you will get a keyboard layout
that really resembles the US layout (but with an Euro key).

Only Apple really gives you „US“ as BTO option, and you really get the real US
layout. Funny story, I wrote an e-mail to Apple, over ten years ago, when they
didn‘t have US layouts as BTO option in Germany... I think it changed
something, because one or two years later, Apple changed it, and you will get
real US layouts ever since on their online store.

~~~
j_4
>in Germany/Europe

Wow, I honestly didn't know how widespread non-QWERTY keyboards are in Europe.
Wikipedia has a nice map.

[https://en.wikipedia.org/wiki/QWERTZ](https://en.wikipedia.org/wiki/QWERTZ)

I live in Poland and we pretty much exclusively have QWERTY. QWERTZ is a
historal artifact. Not sure if that's still the case but at least until
recently, it was installed by default on Windows as an alternative layout,
seemingly mostly to confuse non-technical people when they accidentally press
the Ctrl+Shift combination to swap.

~~~
chrizel
Interesting. But we have to be clear here: It‘s not only about QWERTZ vs
QWERTY. Many countries still have ISO keyboard layout: a tall return key and
the left shift key is short (according to
[https://en.wikipedia.org/wiki/QWERTY](https://en.wikipedia.org/wiki/QWERTY)).
The US keyboard is different: the return key is wide and not tall, and the
left shift key is also wider. If you once got used to the US layout, it‘s
annoying to use an ISO layout, because your pinkies have to move a little
larger distance to hit return and left shift, if you know what I mean. :-)

~~~
j_4
Oh! That's true. I think you have it a bit mixed up though.

\- ANSI is the same thing as US, it's the one with a long left Shift and
single row Return

\- ISO is the one with a short left Shift, two row Return, and the [| \\] key
in two places

I've certainly used both throghout my life, it seems both are common enough
that I never paid it much mind after first learning how to handle a computer
during early childhood.

I just checked and out of the 5 keyboards in my home right now, 4 (laptops)
are ANSI and 1 (standalone, my daily driver) is ISO.

~~~
chrizel
Oh sorry, you are right - I‘ve mixed up ANSI with ISO... thanks for the
correction!

------
ddevault
What this fails to capture is the original motivation behind the design of
Markdown. It was based on things people were already doing to add "markup" to
plaintext things like emails. It was designed to just werk to convert your
normal email-esque writing style into HTML. This article considers Markdown
from the opposite perspective for which it was designed.

In other words, Markdown is not designed to be a simplified markup language
for HTML. It's designed to make HTML a frontend for plaintext. The numbered
lists with *., for example, would be totally unreadable in plaintext without
context.

------
godelski
There's always these "Markdown got X wrong posts" and they seem to be very
browser centric.

You know how I use Markdown 99% of the time? Vim. I LOVE that it is simple and
easy to read in a text editor. I spend a lot of my time in the terminal and
that's WHY I use Markdown. If I wanted fancy things that display better in a
browser, I'll use something else. I look at Markdown as great because they
kept it simple. I can read it easily in vim and I can have some nice features
in a browser (i.e. my GitHub repos don't look like they're from 1995. But they
also don't look like a Geocities nightmare).

I use Markdown to document code. I use it to keep notes. I use it to track
tasks. Etc. It is my digital pen and paper BECAUSE it is simple, because I can
read it in the terminal just as easily as I can read it on the web.

Keep Markdown simple.

~~~
loeg
I also mostly edit Markdown in vim.

I hate that I have no idea how it will render on Github or wherever without
actually pushing a test commit out, or using Github's interactive UI +
copypaste to preview.

There's a bunch of command line tools and libraries implementing a variety of
incompatible supersets of markdown.

Anyway, you can write Markdown-style plaintext documents without trying to
conform to Markdown. The point of markdown is to be able to render those
straightforward documents as pretty web pages without the degree of uglifying
and boilerplate markup that HTML requires.

~~~
godelski
> I hate that I have no idea how it will render on Github or wherever without
> actually pushing a test commit out, or using Github's interactive UI +
> copypaste to preview.

I used to do this a lot, until I discovered Markdown Preview
[https://github.com/iamcco/markdown-
preview.nvim](https://github.com/iamcco/markdown-preview.nvim)

------
swyx
[author here] wow I didn't expect this to shoot up so quickly! Obviously I
love Markdown and use it every day. But like with everything you live with
every day, you notice the little things.

I @'ed John Gruber on my original tweet and readers might enjoy his response:
[https://twitter.com/gruber/status/1240888155307495426](https://twitter.com/gruber/status/1240888155307495426)

------
juped
Org is a way better naturalistic markup format, with way better tooling, but
it's hampered by being emacs-only and having weird devotees who like to sell
it as some kind of task planning tool when really it's a naturalistic markup
format.

I've never liked emacs, but I keep it around for Org, which I use most often
as a LaTeX generator without all the ceremony of actual LaTeX.

~~~
lmilcin
I also love org but it is no replacement for Markdown exactly for the reason
you mentioned. Emacs as a way of life is a no go for most developers.

I may love Emacs but I want to be able to edit my project with something else
if need be (IntelliJ IDEA?) and I definitely don't want to force my users to
any particular IDE. Making my project only really accessible to Emacs users
just to be able to work with document files seems like a very good idea if I
want to discourage them from ever looking at it.

~~~
globular-toast
There's nothing at all tying the org-mode format to emacs. It's a plain text
format which any editor supports and syntax highlighting would be just as
simple as for markdown.

~~~
loeg
Does any editor other than emacs support it in practice? And does the tooling
around it run outside of elisp?

~~~
arh68
There is a Sublime Text plug-in [1], but it's been a while since I used it. I
think it's in Python, not elisp.

If you're just looking to edit Org files, Emacs is hard to beat. I don't use
Org files so much anymore, more OmniFocus & Markdown/Sublime.

[1]
[https://github.com/danielmagnussons/orgmode](https://github.com/danielmagnussons/orgmode)

------
russellbeattie
My firm belief is that if Markdown had never been adopted, we would have a
standard way of formatting text by now supporting these 10 basic formatting
types: headings, paragraphs, bold, italic, strike-through, monospace, bullets,
links, images and horizontal rules. That's it. Just 10 basic formatting
options.

There's no reason why, in 2020, these aren't available everywhere. Just like
every text editor can understand emojis (with colors even!), these simple
formatting rules should be baked into every platform by now, and easily used
on everything from PCs to phones to TVs, in every editor from Vim in a
terminal to email to iMessage to Wikipedia's text entry box. Just like emojis
are. It's truly insane we haven't standardized this yet. How old is RTF or
PDF? Doing this basic formatting in ascii text is just mind-numbingly stupid.

~~~
madhadron
Windows and macOS do carry italics, strike-throughs, and the like through copy
and paste. I think it's the tyranny of the teletype emulator that keeps us
doing this. After all, why shouldn't we issue textual commands to a computer
in a more sane environment?

~~~
ilammy
> Windows and macOS do carry italics, strike-throughs, and the like through
> copy and paste.

There is no magic, they do it by literally exchanging HTML on the clipboard.
Applications use it as a lingua franca and convert the text into whatever form
they use internally.

~~~
orthoxerox
HTML? Not RTF?

~~~
ilammy
I'm not that sure about macOS, but on Windows that seems to be way more
prevalent in my experience (had to deal with it when worked on clipboard
redirection via RDP). The format also has some additional metadata embedded
into it [1]. After all, Windows applications kinda pioneered "rich text"
exchange via clipboard.

[1]: [https://docs.microsoft.com/en-
us/windows/win32/dataxchg/html...](https://docs.microsoft.com/en-
us/windows/win32/dataxchg/html-clipboard-format)

The format is actually negotiated by the communicating applications so it
quite can be RTF too, depending on what formats the applications can produce
and understand and the priorities they give to them.

------
lenkite
Prefer Asciidoc over Markdown. Easier to remember syntax, richer set of
controls and more importantly - _better_ tables. Tables in Markdown are a
nightmare. Asiidoc is a lifesaver for tables. For big tables, columns can be
specified as rows leading to sane reading.

~~~
gerikson
I just ”shell out” to HTML for tables.

~~~
Carpetsmoker
HTML tables are hard to write, read, and edit though. If you want to make the
document easily readable both as HTML and Markdown (quite useful for a README,
I think) then it's not a very good option.

~~~
gerikson
I agree, I've resorted to writing Perl to generate the tables in some cases.

------
cornishpixels
Honestly, the single biggest problem with Markdown is that it's been
implemented in so many different ways by so many different people. This is
largely because a lot of corner cases were simply not defined.

When a website uses Markdown for input, it's extremely tough to be sure of how
to format certain things, especially when multiple different syntaxes combine.
(I'm thinking of things like list+code block; or bold+italics, or list+line
break, etc.)

~~~
hodgesrm
Markdown has similarities with CSV which is also underspecified and has
varying implementations. Even simple things like quoting don't work
consistently across applications.

That has not stopped countless applications from using CSV because it's so
useful to have a simple transfer format. CSV corner cases usually don't hurt
too badly because you can usually rule them out based on the source or sink of
the data.

------
BerislavLopac
And one thing that this article gets very wrong about Markdown: It was not
designed to be a structured markup syntax of any sort. The syntax, in fact,
was never actually _designed_ as such.

Markdown originated as, basically, one guy's attempt to convert instances of
unofficial text-formatting convention, commonly used in text-only
communication such as emails and Usenet, into HTML that can be presented on
the Web. In order to do that he had to enforce some standards, while still
leaving some flexibility (which is why the top levels of headings have more
than one forms; both were commonly used to designate the same thing).

It was only after companies like Stack Exchange and GitHub started using
Markdown as, ironically, a markup language, that there were any attempts to
enforce a standard. I clearly remember a whole online "war", for the lack of
better term, arguing pros and cons of standardisation.

------
vortico
About the header slugs: I don't think the content of the header should be the
anchor ID. Readers will link to it, the author will fix a spelling issue or
whatever, and the link will break and other readers will arrive at the top of
the page when the browser doesn't find the old ID.

My solution that works with most Markdown variants is to use inline HTML to
define an anchor directly before (or after) the header.

    
    
      <a id="stuff"></a>
      ### Things about stuff
    

But of course this isn't much cleaner than just using inline HTML for the
header itself.

    
    
      <h3 id="stuff">Things about stuff</h3>

~~~
chrismorgan
Some tools are now allowing you to manually specify the ID in this way:

    
    
      ### Things about stuff {#stuff}
    

Hugo works that way by default, and I copied that syntax for Zola in
[https://github.com/getzola/zola/pull/685](https://github.com/getzola/zola/pull/685)
last year.

------
ashton314
Shameless plug: I do 99.98% of my work in a terminal, and I'd much rather read
markdown like a man page. I created a little utility to display Markdown
(actually, any kind of file that `pandoc` can read) and displays it nicely
formatted. You can see it here:

[https://github.com/ashton314/marked-man](https://github.com/ashton314/marked-
man)

Hope someone might find it useful. :)

~~~
stragies
I use a variation of the shell-pipeline you use in your `mm` script. I don't
know how to do code blocks here, so I'm pasting the un-commented one-liner

mdv () { pandoc -s -t man ${1:-"-"} |groff -T utf8 -man | sed 1,4d | head -n
-4 |${PAGER:-$(DN=/dev/null; which less &>$DN && { echo "less -FRSEX"; }||
which more 2>$DN || echo cat)} ; }

from my answer here:
[https://stackoverflow.com/a/61029131/5208540](https://stackoverflow.com/a/61029131/5208540)

This is a shell function to add to your environment

------
battery_cowboy
Kinda on-topic (50/50): I'm looking for a flavor of something-like-markdown,
but it would have semantic tagging and some abilities to add my own attributes
to an element/tag (like for links, I want to be able to specify some to open
in another tab, but others to open in the same tab, I'm willing to do that
with raw attributes if I can add them on) for conversion to HTML in a static
generator, is there something like that anyone knows about? (I prefer not to
"roll my own" if I can use a standards-based language)

For instance, I'd want to do the example in the GitHub flavored markdown with
tags like <article> or <aside> around markdown-like syntax. Markdown is so
easy compared to HTML, so I want that ease in my article-writing workflow.

I was considering using HTML directly in a templating language, but I want it
to be a more human-friendly text format, like Markdown.

~~~
arve0
markdown-it [1] has a number of plugins that let you add extra features to
commonmark. For adding attributes, I wrote markdown-it-attrs [2]. Combine that
with a flexible static site generator, like metalsmith [3], and you have a
solution adjustable to your needs.

1: [https://github.com/markdown-it/markdown-it](https://github.com/markdown-
it/markdown-it) 2: [https://github.com/arve0/markdown-it-
attrs](https://github.com/arve0/markdown-it-attrs) 3:
[https://metalsmith.io/](https://metalsmith.io/)

~~~
battery_cowboy
I intend to use this setup, modified a bit, it's pretty much just what I was
looking for: a very modular static generation tool that still uses a language
I can read easily before generation, even if it isn't a 100% standard/stock
language.

I was running into issues where some feature idea I had (ex: a way to expire
an article based on some "code", like a function to check if Debian 10 is EOL
yet in an article on how to install Debian 10) wouldn't be supported by my
static generator, so I wanted to write my own or fork it, but instead I can
just write modules for metalsmith or markdown-it for different features I
need, it's perfect.

------
mnarayan01
> Code Blocks probably aren't necessary

When you're reading raw markdown they're _extremely_ useful for short snippets
since they save you two wasted lines per block.

~~~
Grue3
But these short snippets are useless because you can't easily copy paste them,
especially with some programming languages that are whitespace-significant
(looking at you, Python). And I don't understand how triple ticks are wasted
lines, because you need to surround a code block with empty lines anyway while
triple ticks work straight after line break.

~~~
recursive
If you're using your clipboard, it's invariably going to be at the wrong level
of indentation regardless. What's the correct level of indentation? 0? 1?
more? There's no generally correct answer, so you're going to have to use the
block indent feature on your editor anyway.

------
mmcnl
Why do these articles always pretend to be so know-it-all? I really don't like
the explicit statement that "Markdown got it wrong", leaving no room for
debate. For everything that Gruber supposedly "got wrong", a lot of arguments
can be made for why Gruber got it "right", the author often explains that
himself. That means that a lot of this is subjective. Let's keep the facts and
opinion separate.

~~~
slantyyz
> Markdown got it wrong

You're right. The problem with the statement is that there's a presumption
Markdown was created for the world at large, and I think it was originally
designed for one "customer", who also happened to be the creator. Which means
Markdown got it right.

------
greggman3
Hmmm,

* Markdown in HTML. NO!!! That would drive me crazy. I use HTML all the time for diagrams. If I had to be aware of every tiny place where my content in the diagram was going to get munged by the markdown parser I'd tear my hair out.

* * vs - I've used * my entire life for lists, decades before markdown existed. Never heard of using - for lists until yaml

* auto numbered lists. NO!

The problem is it's nearly impossible to keep your formatting right if you
have a long item lists. I often write answers on s.o. where it's like "You
have 3 issues. 1. several paragraphs 2. several more paragraphs and code
samples. It would be absolute hell to have to figure out the formatting to
make sure auto numbered item 2 stayed 2 and didn't become 1 in a new list

* code block indentation - agreed that code fences are generally better. Worse most places I enter markdown (stackoverflow) don't have any indenting/outdenting editor controls which makes it really painful. Either I had to manually indent 5 to 50 lines or else edit outside stack overflow and paste in. I know stackoverflow has Ctrl-K but it doesn't work once you take in account the list indentation issues.

* no syntax for adding classes

I don't mind that. It kind of feels like part of the point. If I need a class
I use embedded html although that's another place to rant. Inline HTML uses
markdown where as self contained HTML does not. I'd prefer they both didn't.
In other words. If you put

    
    
        The big <span style="color: red">*bear*</span>
    

you'll get a italic red 'bear' but if you put

    
    
        <div>The big <span style="color: red">*bear*</span></div>
    

You'll get red '<asterisk>bear</asterisk>'

Ok, I give up. no idea how to put an asterisk on HN. >:(

As mentioned above I'd have preferred no markdown in HTML as it's bitten me
quite often trying to color code variables in a math description that uses *
and having the * get eaten by being parsed.

* Ids - The id thing does bug me too. Markdown generates ids based on headlines but that's way too brittle. Edit the headline and your ids break. I also wish auto-numbered footnotes were a standard feature that worked by id so I could do something like [-fn-](#someid) and later #fn-someid paragraph a it would insert [<num>] at the top and link to #fn-someid at the bottom.

~~~
NobodyNada
> * auto numbered lists. NO!

> The problem is it's nearly impossible to keep your formatting right if you
> have a long item lists. I often write answers on s.o. where it's like "You
> have 3 issues. 1. several paragraphs 2. several more paragraphs and code
> samples. It would be absolute hell to have to figure out the formatting to
> make sure auto numbered item 2 stayed 2 and didn't become 1 in a new list

I think you and the author agree on this point: Markdown _does_ have auto-
numbered lists, and the author of the blog post believes that was a design
mistake. If you write a Stack Overflow post with a list numbered 3, 2, 1, it
will be rendered as 3, 4, 5.

------
scelerat
Markdown drew its influences from predecessor structured text languages whose
goal was minimum formatting of ASCII text in a structured way such that it
could be parsed and re-rendered into any other format.

The goal was simplicity and readability in plain-text email and Usenet posts
so I'm not surprised that fifteen years from its inception, and thirty or more
years on from some its antecedents, we're using text and thinking about how we
use text differently. One of Markdown's pivots from setext was the addition of
code blocks. In the environment that setext was created, a code block would
simply be rendered much like everything else: in the plain and probably fixed-
width display that your email was also displayed in. By 2004, email had rich
formatting, Usenet was on the wane, and people still needed a lightweight text
format to share. Markdown filled that need, as did a number of other similar
alternatives, though I forget their names.

My first exposure to such lightly-formatted ASCII was setext [1] which was the
format chosen for the Mac- and Apple-oriented TidBITS email newsletter [2]. As
a contributor to that newsletter, Gruber would have been intimately aware of
the format.

Twenty years ago, I used setext in code projects basically the same way as
nearly everyone uses Markdown now. I like OP's suggestions though I've always
liked the 'lazy' approach to ordered lists.

[1] setext:
[https://en.wikipedia.org/wiki/Setext](https://en.wikipedia.org/wiki/Setext)

[2] TidBITS: [https://tidbits.com](https://tidbits.com)

------
foolfoolz
i actually disagreed with a lot of these. markdown is opinionated. the feature
set is limited. the output looks almost all about the same. this is the goal.

no one wants the myspace outcome of simplifying messages. you usually don’t
need much styling but the tools that markdown includes are good enough. if you
need more you probably want to ask why you’re writing in a place that only
accepts markdown

~~~
slantyyz
> markdown is opinionated.

This. If I were to guess, Gruber made Markdown to make writing for his blog
easier. Then he made it available for whoever wanted to use it too, which was
very nice of him.

Given how there are already multiple flavors of Markdown available that
address various shortcomings, I don't know if there's a point to critiquing
Gruber's original version of Markdown since it was likely created to satisfy
his writing requirements first and foremost.

------
okapii
You create empty lines by adding two spaces at the end of lines. MD has
invisible syntax. To me this without doubt is the worst thing about MD.

------
SeriousM
Things it did right: It was the right tool at the right time. Everyone knows
it and can use it. It's like Javascript for documentation.

------
wackget
There's also no way to create vertical tables with headers on the left:

[https://stackoverflow.com/questions/60995936/vertical-
table-...](https://stackoverflow.com/questions/60995936/vertical-table-
headers-i-e-headers-on-the-left-in-markdown)

------
brianzelip
> There's nothing I hate more than reading a good article with headers,
> wanting to link someone directly to the section relevant to them, and then
> not having an id to use to send them straight there.

Lots of other things I hate more than this, but dagnabit this drives me nuts
too!

------
Already__Taken
The second you want to do code and images on a page I just spend all my time
fighting whatever markdown workflow is in place. Which would be fine if it
added anything but they never just work, you still need to do your own image
optimisation and aligning images or custom layout sections is terrible or not
possible.

Markdown is harder to work with in the long term than just wiring HTML with
Emmet. That's my opinion a few years ago and these days I'd double down on it
as editors are so good.

Tables suck in everything so we should standardise a json and/or csv import
language to drop tables in a built time anyway.

Markdown is good for notes. Even mermaid diagrams are kind of unpleasant to
write.

~~~
jdeisenberg
Yes. At times I would like to be able to use italics in a code block to
emphasize some portion of the code, and that seems very difficult, if not
impossible, to do.

I realize this would conflict with automatic syntax highlighting, which is
probably why it is not allowed.

------
KKPMW
Some of those things are addressed in my favourite markdown variant -
multimarkdown
[https://fletcher.github.io/MultiMarkdown-6/MMD_Users_Guide.h...](https://fletcher.github.io/MultiMarkdown-6/MMD_Users_Guide.html)

The author has found a sweet spot between being very conservative with the
original declarations and adding the missing functionality. It also comes with
an amazing lightweight implementation written in C that behaves correctly:
gets input from stdin or a file and passes it to stdout, without the -o flags
that (e.g.) pandoc is using.

------
freepor
People put too much behind Markdown is what happened. It was just a random
idea on a blog post. But people made it a universal authoring standard and it
is just not up to the task.

------
suref
I'm currently working on a markdown system where I wanted to extend codeblocks
to be able to incorporate more information. The `js:title=example.js` just
doesn't cut it. Want I landed on was some sort of yaml-ish format:

    
    
        ```
        ***
        property1: ...
        property2: ...
        ***
        code
        ```
    

This way multiline properties are supported and I can also incorporate
markdown inside the properties themselves.

------
blackrock
Markdown has been a godsend.

It’s just what I wanted. Something text based, where I can sorta control some
formatting, but isn’t tag heavy like HTML.

I just need it to format a few things, to make it easier for myself to consume
later.

The most useful for me is actually the syntax highlighted code blocks.

I use it mostly for brain storming, planning, and scratch work.

------
pm90
I was turned on to ReST by a coworker and prefer it over Markdown.
Aesthetically ReST code seems easier to read in raw form; and it’s somewhat
more predictable in what works and what doesn’t because bad reST code breaks.

------
jesse_m
I can't stand the invisible syntax like double trailing space.

------
chrismorgan
reStructuredText on these, for anyone that’s curious or thinking about it:

1\. If you use “5.”, it’ll give you a five. If you want auto-numbering, use
“#.” as your prefix. (While I’m thinking of it: I hate that using actual
Unicode bullets like “•” doesn’t work in Markdown, and that in
[https://talk.commonmark.org/t/unicode-character-
bullet-u-202...](https://talk.commonmark.org/t/unicode-character-
bullet-u-2022/397) it’s been actively rejected for CommonMark.)

2\. Code blocks are by indentation only, no fencing, but avoids confusion
about indentation levels by defining all of that stuff _properly_ and having
it match visual usage, rather than Markdown’s crazy “four spaces, but in
certain situations we’ll let you get by with 3, 2, 1 or even 0—but if you then
seek to nest, remember to bump it up to eight rather than just N+4”. Code
blocks are indicated by `::` at the end of or as the entire previous
paragraph, which is esoteric, but also fits in very well with its directive
syntax, which is how you can attach extra metadata to code blocks. It’s
definitely not as simple as the newer Markdown fencing approach, though it
fits into the rest of reStructuredText in a sane and principled way so that
it’s not at all hard. Still, I think that a new version of reStructuredText
would quite possibly include fencing in some form—or maybe directives would be
resyntaxed to be able to be fenced rather than indented, though achieving that
while still allowing nesting would take care.

3\. Markdown in HTML in Markdown? That Markdown extends HTML is the real
problem here, and is both its greatest strength and help in adoption, and its
_catastrophic_ weakness. reStructuredText is a language of its own that
doesn’t extend anything, so that style of HTML output is typically done by
defining new directives, which can then contain reStructuredText. It’s
strictly less powerful, but it composes _way_ better. As a workaround, the
`raw` directive lets you put in arbitrary HTML (or LaTeX, &c.).

4\. By deliberately not being HTML, reStructuredText handles this sort of
thing much better. Each node in the document can have classes (which will end
up as class="…" in HTML, something else in LaTeX, &c.). You can do things like
`.. class:: …` to apply a class to the next block (heading, paragraph, list,
&c.). Most directives support a :class: option. You can define new roles so
that :classname:`…` will do what you desire. And none of this is then tied to
HTML.

5\. reStructuredText lets you define anchors at any place in the document
(which can also be used for index entries when writing books or things like
that). `.. _anchor-name:` above the heading will do it thus. This protects you
against the anchor changing (and thus breaking links) if you change the text
of the heading. Any form of automatic heading ID generation is left to the
software to decide, e.g. Sphinx generates IDs by default.

6\. Field lists. A field list at the start of the document is treated as
document bibliographic data, and you can put anything in there you like.

I myself prefer reStructuredText in almost all regards, but I scarcely use it
any more other than for a couple of types of personal documents, because of
the ubiquity of Markdown. It was similar with Mercurial and Git.

~~~
jurip
It's weird how both ReST and Markdown stumbled on that indentation thing. And
ReST has the awkward header underlines, too. Both of those are annoying at the
best of times and basically unusable with proportional fonts (and we're
dealing with prose here, where there should be no reason to force people to
use monospaced fonts if they don't want to.)

If I'm ever involved in designing a syntax like that, the first hard and fast
rule will be that the user should never have to count anything, especially in
relation to anything else.

~~~
chrismorgan
reStructuredText is very committed to the plain text visually matching the
formatted. For headings, visual underlining makes sense in that context. And
code is conventionally indented, so it also makes a lot of sense. (Blockquotes
are indented as well, differing from code blocks by the absence of `::` at the
end of the preceding paragraph; indentation again matches conventional
appearance. But that’s a place where I get where Markdown’s coming from, using
> indentation like in emails.)

In more recent times, convenience of writing has become a more important
concern to people, because these formats have shifted from niche use by
dedicated people in real text editors that would like what they see to match
the end result fairly well, to mainstream use in textareas and similar, and
sometimes even WYSIWYG editors. That’s what’s driven people to prefer the
convenience of code fencing, because indenting each line in a textarea is a
_pain_. Ditto on headings. If reStructuredText were being redone now, I think
it’s fair to say that prefix rather than underlined headers would be at least
an option. It would just remain to be seen whether they went with `###`
meaning level 3 even if there was no `##` or `#`, or whether they’d boost it
up to level 1 or title, as appropriate.

------
jesse_m
I can't stand the invisible syntax like a double trailing space is some valid
syntax.

------
andrew_
TL;DR - "Markdown is too simple for me, I'd like it to be more nuanced"

I'm not saying that to be cheeky. The article can be boiled down to that
because the author is looking for HTML features in Markdown, when there's very
little need. e.g. we don't need classes in markdown and we don't need IDs or
`name` attribute specifiers because that can be accomplished already by mixing
in the HTML that one needs.

------
kerkeslager
I agree with some of this (i.e. the numbers), but I think it's coming from a
place of not understanding what Markdown is for. For example, your complaint
about indentation for code blocks makes no sense if you're using Markdown
appropriately.

The original idea was to take emergent syntax used by text file authors as
cues for humans reading text files, and use that as a syntax for generating
HTML, so you could use text files as the source of truth for generating HTML.

Backticks aren't an emergent syntax used by text file authors as cues for
humans reading text files--that's a syntax directly intended for generating
code blocks in HTML, with little semantic value if the markdown is going to be
consumed as text.

If your goal is to have something consumable as both text and HTML, then some
sacrifices have to be made, because text simply can't do everything that HTML
can. The error-prone indentation syntax is just a compromise, but there were
features that were left out completely. The original markdown didn't contain
underline or strikethrough, for example, because text can't do those things.

The problem is that for a few years, this idea turned out to be useful as a
way of allowing users rich text editing capability on websites. So people
wanted Markdown to do everything that HTML could do, hence we get underline,
strikethrough, code fences, etc. This hurts use cases where markdown is used
for its original purpose, because modern markdown isn't as nicely consumable
as text files, but users didn't care because they weren't using Markdown to be
consumable as text files. And this made sense for a while.

And where this becomes stupid is that if you don't care about it looking nice
as text, then you shouldn't be using Markdown. There are a wealth tools for
rich text editing on the web (TinyMCE being the most obvious choice, but not
the only one available) and they're FAR superior in user-friendliness to
Markdown. Many actually support Markdown, but there's less and less reason to
even expose that functionality to your users. If you don't care about how your
Markdown looks as text, then just use HTML and edit it with a rich text
editor.

There's another use case where you want to compose HTML content without the
overhead of actually writing HTML, but you want to "do it like a coder", so
using a rich text editor isn't appropriate because you want to be able to diff
and whatnot. But in that case, there's _still_ no reason to be using markdown,
because if you're "doing it like a coder" than you can _just write code_ which
makes what you're doing much clearer, and give you a lot more power. Textile,
Org-Mode, LaTeX are all better options.

GitHub has persisted in using Markdown well past the advent of mature web text
editors, because they still seem to be operating under the illusion that
nontechnical users will become a significant part of their user base. Slack
and Reddit are both moving toward fully rich text, and the fact that they are
still trying to expose their Markdown roots just makes their rich text painful
to use. MediaWiki using their markup language still, probably because they are
blocked by the enormously difficult task of migrating an _enormous_ amount of
content, but if you're starting a new project, you don't have any of the
tradeoffs that these organizations do, so you shouldn't make the mistake of
following in their footsteps.

------
RMPR
Typo

> differnt types of content.

------
jimmaswell
What was even the motivation in the first place to not respect newlines?

~~~
kccqzy
I assume you are talking about the fact that adjacent lines are merged into a
single paragraph.

Have you written traditional plain text emails or write any plain text
documents? You almost always hard wrap your lines for readability. Even in
HTML, newlines are mostly equivalent to just spaces.

~~~
Carpetsmoker
This is also very advantageous in diffs; diff-ing a Markdown file with many
1000+ character lines is rather hard.

~~~
jimmaswell
When does a markdown line get that long?

~~~
Carpetsmoker
When people write it like that?

------
jakear
Hot take (maybe): GitHub flavored markdown is the ideal markup language. If
the author’s ideas were actually better, we’d use them instead.

It supports code well, it supports non-enumerated lists well, it supports
enumerated lists well (if you don’t want view it in rendered markdown, you can
view the raw and just disregard the numbers, understanding that the items are
supposed to be sequential). It supports links well. It supports images well.
It’s easily readable, even with no prior context (@toml, yaml, etc.).

It does whatever a static website could want, and it does it all decently
well.

~~~
judge2020
People tend to use whatever they have to use to be on a platform since these
different parsers aren't portable. Everyone is on GH for the code hosting,
getting a markdown editor that works is a bonus. If you go to any other
community that uses a different markdown standard or even something that's not
markdown, people will be using that - not because it's better than GH flavored
markdown, but because that's what's available.

~~~
b0rsuk
Github supports reStructuredText just fine. You can even display images in
Readme without any extension, just a plain image directive.

