
Why Markdown Sucks (2016) - MilnerRoute
https://joearms.github.io/#2016-03-21%20Why%20Markdown%20Sucks
======
Aardwolf
For me it sucks because it ignores single newlines

Almost any place where I have to type markdown feels like it's plain text
(typing a readme in an actual plain text editor, a git comment in vim, a plain
text box like this one here in hacker news and reddit that also ignores
newlines, ...), and plain text is supposed to listen to your newlines

But markdown will happily turn your two things you put on separaate lines into
a single line, ruin source code or ascii art without adding special
formatting, etc...

It should wrap long lines, but should listen to explicit newlines. The
simplest text editor can, and does, do that.

~~~
phicoh
I'm old school. I like my source files to be at most 80 characters wide. So
for plain text, yes a markup language should reformat paragraphs.

Pre-formatted text is different. But that usually requires a separate context
to make sure that all space stays in place, not just newlines.

~~~
Aardwolf
The problem is that in most cases where I have to use markdown, it's not a
source file. E.g. if in a git comment I use a single newline to separate some
points, it's often a surprise to then find them concatenated on a single line.

Like this very hacker news comment box here. I know it's not really markdown,
but it also ignores single newlines. Why?

Markdown is not really presenting itself as being source code, or at least
it's not being used as such in many places. If you want source code, why not
use something more powerful than something that tries to look like plain text,
except it alters your whitespace?

Also, in programming source code it's natural to try to keep it within 80
characters. But markdown is for writing natural language, isn't it a nightmare
then to keep all lines 80 characters if you edit previous sentences or insert
a word somewhere?

~~~
phicoh
Markdown has a syntax for bullet lists, why not use that?

The nice thing about standards is that there are so many to chose from. It
would be nice if there were a single light weight markup language.

In many contexts you need something where text can be reflowed. Hacker News is
a good example. It would be bad if all comments with long lines would show up
with scroll bars.

So if the output is going to be reformatted anyhow, then it is better to use a
light weight markup language that provides a quick way to provide the most
common rendering hints.

And at that point your input text is source.

~~~
Aardwolf
> It would be bad if all comments with long lines would show up with scroll
> bars.

No it woulnd't, more newlines (by not ignoring single newlines) would make
lines shorter on average, not longer.

It should of course auto wrap long lines (and plain text does), horizontal
scrollbars suck.

So markdown only makes you choose between ignoring your single newlines or
preformatted text with horizontal scrollbars but cannot combine best of both
worlds? That makes it _even worse_.

------
vimslayer
ITT people giving completely contradictory opinions on what features markdown
should or should not have.

Markdown is (relatively) simple and opinionated. If you don't like it, use a
different markdown flavor or different markup language. But don't expect other
people to agree with you on the superiority of that markup language, because
they probably would have wanted a different one.

------
sradman
This is an old post. After doing some quick searches I think this rant was a
bit premature. I think the problem boils down to Jekyll _config.yml options
that should have been specified in the GitHub instructions. Specifying
kramdown is not enough, I think you also have to specify the Jekyll defaults
for kramdown which includes "input: GFM"

[https://jekyllrb.com/docs/configuration/default/](https://jekyllrb.com/docs/configuration/default/)

Backquote fencing for code blocks seems to be the default in GFM so it not
working for the OP seems like a config issue. I'm not sure if the default
"smart_quotes: lsquo,rsquo,ldquo,rdquo" is compatible with the LaTex quotes
the OP uses but there may be a configuration that works for him as well.

Markdown, like all serialization formats, will always have baggage. Once any
syntax makes its way into the wild, it is forever unless you are willing to
make backwards incompatible changes. This is also true for public/published
APIs. SQL is a bit of both serialization-format-DSL and API-DSL. There are all
kinds of brain-dead SQL language choices, both standardized and vendor
specific, that are supported forever.

------
wallstprog
I use Markdown and find it quite useful, even with its problems (which the
article does a good job of describing -- the main one being "The nice thing
about standards is that there are so many to choose from".)

Apropos of GitHub pages (which I use to host my blog), are you aware that it
is possible to generate HTML locally from Markdown, and then publish the
generated HTML? FWIW, Octopress
([http://octopress.org/docs/deploying/github/](http://octopress.org/docs/deploying/github/))
does this (I didn't even realize at first that was what was happening), and
that happily insulates you from any changes in GitHub's Markdown support -- as
long as your local toolchain remains consistent, content should be rendered
the same.

------
coldtea
People using the term "sucks" seldom have a valid criticism (and never a
subtle one).

The problem here was GitHub making an abrupt change (and switching defaults),
not Markdown itself.

Which has its problems, but those are not it.

------
carlmr
AsciiDoc is pretty good because it's similar enough and standardized better.
Also more extensible, yet a bit more complicated to get running.

~~~
eeZah7Ux
AsciiDoc is really underrated. It's the only format that is simple and
readable like MarkDown and yet is powerful enough to write whole books.

~~~
TuringTest
That may be because of the vicious cycle of lack of popularity, which leads to
worse tool support, which leads to people preferring Markdown-based tools,
which leads to increased spread of markdown and less popularity for AsciiDoc.

One lesser known fact of AsciiDoc is that it's a markup syntax for DocBook, so
it supports the full feature set of this book-creating toolchain. Markdown can
only dream of having support for more than simple web pages and single-page
documents.

------
romwell
FWIW, this blog is written using TiddlyWiki[1] whose WikiText syntax is
markdown-like[2]. (Click on the pencil icon to see the raw text).

So perhaps "This Wiki's syntax" can be added to the list of alternatives that
the author likes, given that he's written this whole blog in it :)

[1][https://tiddlywiki.com/](https://tiddlywiki.com/)

[2][https://tiddlywiki.com/static/WikiText.html](https://tiddlywiki.com/static/WikiText.html)

~~~
acqq
And maybe fitting, the blog entry contains broken formatting at the end:

"LaTeX is better than markdown by far, but it has a fundamental

flaw. The computer decides where the text goes, not me - I want to be in
command."

~~~
leemailll
>"The computer decides where the text goes, not me - I want to be in command."

Is that possible for any program to do it in plaintext? The only things I know
that can fully control character positions are something like inDesign, I
don't see anyone would like to write a paper in it.

~~~
acqq
> Is that possible for any program to do it in plaintext?

Sure, TeX.

~~~
leemailll
The above quote mentioned the quoted one wants to take full control of
character position, is this achievable with plain TeX?

~~~
NikkiA
Yes, but it'd be painful.

------
majkinetor
The main benefit of Markdown is its simplicity and intuitivness, it is based
on email behavior.

There are certainly way better systems, such as reST. The problem is that reST
is way harder to learn and less forgiving then markdown.

I used python Sphynx for project docs and recently moved to mkdocs. With
enough customization[^1], I would say that experience is almost identical. The
one thing I like more about Sphynx is that you don't need to depend on
document locations on file system, and as a older platform it has much better
plugins.

On the other hand markdown is everywhere now, IT people usualy know it and
non-IT people can learn it too, which is valuable in many domains - for
example I ask my BA to write functional specification in markdown and PlantUML
so that it can be put in a feature branch along with other code, so devs can
follow how it progress withs diffs etc. rather then having one big Word file
which is typical otherwise.

[^1] Here is what I use: [https://github.com/majkinetor/mm-
docs](https://github.com/majkinetor/mm-docs)

------
indentit
I guess this isn't so relevant now that CommonMark and GFM specs and reference
parser implementations exist, though I know they don't cover some fairly
popular things like footnotes from "markdown extra"...

------
hestefisk
Oomph. XSL-FO. I used that for a custom PDF templating engine once. I think it
was called XSL-FOP. Worst XML nightmare that doesn’t lend itself very well to
version control. I would prefer markdown any day (or, indeed, using LaTeX with
a non-PDF output). Even plain text is preferable.

~~~
Mikhail_Edoshin
FO stands for "Formatting Objects" and FOP is "FO Processor", e.g. Apache FOP.
The format is not meant to be user-editable, of course, it's an intermediate
step, but as a page description language it's very good. I myself use it when
converting reStructuredText sources to PDF.

------
Fire-Dragon-DoL
If I'm not wrong, you can use directly the br tag in your markdown (instead of
the invisible double white space) to mark end of line. That's enough for me

------
eudora
The author makes the point that a standard is required.

I've heard of various implementations like kramdown and redcarpet behaving
differently, so it seems that that is the case.

------
bdowling
Markdown sucks because the lowest level headings, the ones you use most often,
require the most typing of #s.

~~~
mrec
Counterargument: you don't always know when you start writing a document how
many levels of heading you're going to end up needing. A rough outline is
inherently top-down, not bottom-up, so keeping your granularity options open
makes sense.

~~~
tylerhou
Counter-counter-argument: you can always dynamically adjust heading levels
based on how deep you have headings in your document. So maybe:

#### = h1; # = h4 initially.

If you have ##### (5) anywhere in your document, then ##### = h1 and # = h5.

If you have ###### (6) anywhere in your document, then ###### = h1 and # = h6.

~~~
mrec
Not sure I follow. You're not going to suddenly discover after two days of
writing that you need a top-level header for the whole document, but you might
very well discover that one of your "leaf" sections needs to be broken up
further. The difference being that in your scheme I'd need to change _all
existing headings in the document_ to handle that.

Another (minor) thought: if you're the type who starts by outlining the whole
doc with headers only, the Markdown approach naturally makes indentation
follow structure.

------
amelius
The proof of a markup language is if you can document itself in it without too
much problems.

------
fxfan
Neither markdown nor any of the other light weight marktup languages mentioned
here (so far and likely till expiry) can do numbered lists ;)

~~~
indentit
Perhaps you could explain that a bit more, please? AFAIK, HTML's "<ol><li>"
tags work just fine, as does Markdown's "1." syntax...

~~~
fxfan
Sure.

I wasn't counting HTML's ol tag, that's not fair :)

1\. Nissan 2\. Tesla 3\. BYD

To (god forbid!) remove Tesla, you have to write

1\. Nissan 2\. BYD

Now generate a diff:

    
    
      -- 2. Tesla --
      -- 3. BYD   --
      ++ 2. BYD   --
    

Ideally the diff should be:

    
    
      -- <some marker> Tesla --

~~~
chrishannah
Although I would argue it looks better, you don't have to use sequential
numbers when defining ordered lists.

Taken from the Markdown Syntax Documentation
([https://daringfireball.net/projects/markdown/syntax](https://daringfireball.net/projects/markdown/syntax)):

It’s important to note that the actual numbers you use to mark the list have
no effect on the HTML output Markdown produces. The HTML Markdown produces
from the above list is:

    
    
        <ol>
        <li>Bird</li>
        <li>McHale</li>
        <li>Parish</li>
        </ol>
    

If you instead wrote the list in Markdown like this:

    
    
        1.  Bird
        1.  McHale
        1.  Parish
    

...

you’d get the exact same HTML output. The point is, if you want to, you can
use ordinal numbers in your ordered Markdown lists, so that the numbers in
your source match the numbers in your published HTML. But if you want to be
lazy, you don’t have to.

~~~
intertextuality
Although not exactly aesthetically pleasing, I actually prefer the 1. 1. 1.
layout. Why? Because when you write something it's common to revise and re-
order things. A lot. Having 1. 2. 3. means I'd have to go and fix the rest of
the list.

I see 1. 1. 1. like appending commas to every field in a struct declaration or
an object constructor. It allows me to go back and arbitrarily move things
around.

------
thomasedwards
Markdown doesn’t suck.

Markdown parsers suck, because they’re all different.

Markdown has a spec, but nobody follows it because they want it to do more.

Obligatory xkcd: [https://xkcd.com/927/](https://xkcd.com/927/)

~~~
tkfu
Markdown doesn't have a spec. There's a "syntax description", which leaves a
lot of ambiguities, and the original Perl script, which you could consider a
reference implementation. But there certainly isn't a spec.

(Or, alternatively, there are several competing specs, like CommonMark,
Standard Markdown, and GitHub-flavoured Markdown. But your comment seems to be
suggesting that there's one authoritative spec, which there definitely isn't.)

~~~
joeblau
Markdown does have a spec created and posted by the person that invented it,
John Gruber[1]. The problem is that people keep adding features to it and no
one follows the actual markdown spec.

[1] -
[https://daringfireball.net/projects/markdown/](https://daringfireball.net/projects/markdown/)

~~~
tkfu
That's not a spec, and it doesn't claim to be one. It's the syntax description
that I referred to above. A spec needs to unambiguously <em>spec</em>ify the
grammar.

~~~
joeblau
John didn't invent it for everyone to implement it on everything on the
internet. He invented it for him to use on his blog because he's a writer and
wanted to focus on his content, not on writing HTML. Just because it's not
"specified" that doesn't mean it's not the canonical spec. All of the other
additions that aren't on that page aren't based on the canonical version of
Markdown.

------
louiechristie
Ever tried linting and using prettier with markdown? While working with a team
some use atom, some vscode editor? Different linters apply different rules.
Ended up having to avoid advanced markup features like lists within lists.
Which is annoying when you are writing a readme step-by-step document and need
a step 2.b) for example.

This article suggests using XML. XML is based on an older markup language
called standard generalised markup language ‘SGML’. Why not go the whole hog
and use that?

I found this great little markup language descended from SGML, that is
specifically designed for documentation and is great for the use case in this
article of blog posts. (The markup language has support for links and is
designed to work on screens of any size, all of this was baked in to the
language from the start, not bolted on to a scientific paper markup language
like LaTex.)

It’s called hypertext markup language or ‘HTML’.

Also, your document can be styled using a styling language called cascading
style sheets or ‘CSS’. [But this is optional]. And you can change the styling
of your document years later without changing the text.

For blogging, there is also a popular graphic user interface to ‘HTML’ and
‘CSS’ called Wordpress.

In 2019 it powers 1/3 of the Internet.

~~~
lmm
I tried it and it's awful. Finger-twisting angle brackets everywhere. You have
to balance not just closing brackets but also match the exact formatting
"tag", so rather than "* Foo" it's "<li>Foo</li>" (urgh). It's actually even
worse than XML because you have to do these "closing tags" even when they
don't make sense, so e.g. rather than an embedded image being "![mouseover
text](path)" it's "<img alt="mouseover text" href="path"></img>" (yes,
really). To make it even more fun, if you "cross tags" like "<b>blah
<i></b>blah</i>", rather than giving an error it will silently work most of
the time except when it doesn't.

The available formatting tags are a complete mishmash. There are two different
ways to do a bunch of things (e.g. "<em>" and "<i>" do the exact same thing
but you're supposed to use "<em>" because it's "more semantic" \- apparently
screenreaders don't understand "<i>" even though it's older??). There are
distinct tags for acronym versus abbreviation but no-one uses either of them
because they don't display consistently. But for actually structuring your
text all you get is paragraph and headings - there's no way to mark a section
as a summary. Strikethrough is a mess (early versions had a sensible "<s>"
tag, but now there are two different "semantic" tags that no-one can agree
on).

Don't even get me started on CSS. "You can change the styling of your document
years later without changing the text" \- it seems like no-one working on this
nonsense format ever realised what a _terrible_ idea that is. Your text might
refer to the figure on the left, but the "styling" that defines whether the
figure goes on the left or the right is in a completely different part of the
source. Better still, you have to use this ridiculous action-at-a-distance
"selector" language to define which "tags" the styles actually apply to, so
you cut and paste a paragraph to a different place and magically all its
formatting changes.

Version 3 of HTML was just about usable - you could do formatting inline and
there was only one tag for how to do a given thing, and it usually had a
sensible name (e.g. b for bold, i for italic). The CSS-based versions are just
bad design at every level and I've no idea why anyone would choose them as a
source format over literally anything else.

