
Why Markdown Is Not My Favourite Language (2012) - pmoriarty
http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favourite-language/
======
tptacek
Part of the problem is that people don't really grok the point of Markdown.
There's a reason it doesn't support tables, or a syntax for making the kind of
language used in a code snippet. The point of Markdown is to mimic the
conventions of ASCII-text email, both to make writing it as natural as
possible, and to make Markdown pleasant to read in both ASCII and HTML.

If you want something more featureful than Markdown, the problem isn't
Markdown; it's that you're using the wrong tool for the job.

~~~
pmoriarty
org-mode in emacs supports tables, and it's ASCII-based.

Here's an example, displayed exactly how you would see it marked up in org-
mode syntax in emacs:

    
    
      |-----+-------|
      | Key | Value |
      |-----+-------|
      |  00 | foo   |
      |  01 | bar   |
      |-----+-------|
    

org-mode can export to HTML, and many other formats.

~~~
josteink
Org-mode is a beast. A _fantastic_ beast, much like Emacs itself. You dive in,
but there's always more to learn. Some things may be for you and some things
don't. Everyone should give it a try.

A little known fact, even among most org-users: Github can render org-mode
files to HTML directly if checked into a repo, thus you can write your README
files as org-files.

Shameless example: [https://github.com/josteink/csharp-
mode/blob/master/README.o...](https://github.com/josteink/csharp-
mode/blob/master/README.org)

This alone was enough to make me drop Markdown as my go-to format for semi-
formatted text-files.

A subtle killer feature here is org-babel. You can embed proper code in your
text-files and have your editor (at least Emacs) understand them as such.
Which makes it excellent for writing technical documentation for projects
where code is involved.

~~~
TazeTSchnitzel
>Github can render org-mode files to HTML directly if checked into a repo

They also support ASCIIDoc, ReST, MediaWiki markup, Creole, etc.

See: [https://github.com/github/markup](https://github.com/github/markup)

~~~
donniezazen
I really wish that other services would be like this. You enter text in a few
popular markup languages and not one specific language.

------
BerislavLopac
Markdown. Is. Not. A. Language.

Markdown was never intended to have any particular standardized syntax -- it
was simply a script that took a common syntax used for a long time when
formatting plain text and convert it to formatted HTML. The attempts to
standardize it are misguided, as there is absolutely no need for that -- there
are numerous existing standards for precisely that, starting with ReST which
follows a pretty similar syntax (in fact, any attempt to standardize Markdown
will end up with something very similar, as it has to solve all the same
issues).

~~~
stormbrew
Since when does something have to have a standard syntax to be a language? I
mean, if you said "it's not a programming language" because it's not really
executable in even a limited sense, I'd get that, but to say it's not a
language -- a means of communicating information -- is just absurd. There's no
standard BASIC, and there are almost certainly hundreds if not thousands of
variants of it, but no one would say it's not a language because of that.

~~~
BerislavLopac
No, I meant a "markup language". And you're right -- Markdown is not "a means
of communicating information"; it's a script that converts one form of
information to another.

~~~
Retra
Markdown isn't a means of communicating information?

~~~
BerislavLopac
Only partially. Technically, it is simply a conversion mechanism that converts
one form of formatted text (the "Markdown" syntax) to another (HTML). Now,
since the original format has never been formally specified, instead only
being loosely defined by years of practice in email and Usenet messages,
Gruber had to specify some constraints for his script to follow, but this is
far from a standard.

If we assume there is a standard, it's not called "Markdown", as Gruber
heavily opposes that. On the other hand I'll agree that, if we extend the
meaning of the term "Markdown" to cover a stantard like CommonMark, in that
case yes, Markdown is a means of communicating relatively minor elements of
information -- such as emphasis or lists -- as any other markup language.

------
tonetheman
Newer markdown stuff here: [http://commonmark.org/](http://commonmark.org/)

Gruber did not want them to use the word markdown so they changed to
commonmark. And they are trying to standardize with a spec. I would also
consider it along with your other alternatives.

~~~
TazeTSchnitzel
CommonMark doesn't really fix much given it's not so much a proper spec as a
set of tests, and most big users (who wrote the spec!) aren't actually using
CommonMark anyway.

~~~
pyre
> most big users (who wrote the spec!) aren't actually using CommonMark
> anyway.

I'd say this is partially due to inertial. Reddit and StackExchange for
example, have communities that have been writing in their variants of Markdown
for years at this point.

------
ams6110
I don't like any of them. Markdown, ReST, various wiki/forum dialects of
"simplified" text formatting. They are all as complicated if not more
complicated than just writing HTML. They all have a bunch of rules and special
cases. I'd rather just write in HTML which I already know.

I don't understand the motivation for any of these "alternative" markup
formats. Normal non-technical people want Word (or at least, some kind of
WYSIWYG text entry). I've been on projects where they tried to get non-
developers to use ReST and it was an abject disaster. The tech writers
revolted and refused to use it. So then a developer had to be sidelined to
convert their Word documents to ReST so that we could produce HTML.

Yeah HTML is not perfect, but neither is any of these other markup languages.
If you like one, fine, but don't wonder why none of them has really caught on
outside of small niches of highly technical people.

~~~
cespare
> They are all as complicated if not more complicated than just writing HTML.
> They all have a bunch of rules and special cases. I'd rather just write in
> HTML which I already know.

I find that Markdown is significantly easier/faster to write than HTML and,
more importantly, easier to read in its un-rendered form. To me (and
presumably lots of other people, given Markdown's ubiquity) it's well worth
learning the relatively small syntax.

Edit: Here's a quick comparison with a README.md from one of my projects:

Rendered:
[https://github.com/cespare/reflex/blob/master/README.md](https://github.com/cespare/reflex/blob/master/README.md)

Markdown:
[https://raw.githubusercontent.com/cespare/reflex/master/READ...](https://raw.githubusercontent.com/cespare/reflex/master/README.md)

HTML:
[https://gist.githubusercontent.com/cespare/ad6c41aa28583cac8...](https://gist.githubusercontent.com/cespare/ad6c41aa28583cac8b2c/raw/98f0da452068a0db2719002d0b0fd0654dd5faf4/md.html)

Three things I notice from this example:

\- The verbosity of an XML syntax with HTML is annoying, particularly the need
for closing tags. <code>xyz</code stands out as particularly verbose (compared
with `xyz`).

\- Having to escape certain characters like &amp; makes this HTML sample
harder to read (this is more of a problem with technical/code documents).

\- Automatic linkification prevents stuttering: <a
href="[http://example.com">http://example.com</a>](http://example.com">http://example.com</a>)

~~~
canadev
I haven't seen it used outside of Rails apps, but have you ever tried Slim? I
understand there's a similar tool for Node.js called Jade.

[http://slim-lang.com/](http://slim-lang.com/)

    
    
      table
        tr
          th Col1 Header!
          th Col2 Header!
        tr
          td Col1 Value...
          td Col2 Value...
    

Renders to HTML.

~~~
RobertKerans
Slim/Jade/HAML etc are templating languages, they're not designed for writing
text at all - they're almost the opposite of markdown et all.

~~~
canadev
I wouldn't say they're the opposite of Markdown, but that's not really the
point I was getting at anyway. The poster I was replying to was saying that
two of his issues with using HTML to write documents were the verbosity and
the escaping. Slim solves those two issues.

~~~
RobertKerans
Ah, apologies, point taken. Note that most of that style of templating
language include markdown filters as well - so you drop :markdown in, then
just write a block of text, works really well.

------
rcarmo
I've been using Textile for ages, and it's much better than Markdown for just
about anything _except_ footnotes (in MultiMarkdown) and pieces with multiple
references to the same URL.

In particular, Textile has great table syntax, which I use extensively in
pages like
[http://the.taoofmac.com/space/infoviz](http://the.taoofmac.com/space/infoviz)
(markup at
[http://the.taoofmac.com/media/infoviz/index.txt](http://the.taoofmac.com/media/infoviz/index.txt)).
But over the years I became so used to Markdown (largely thanks to the
profusion of editor support it spawned) that I mostly gave in.

Still, Creole might be a good addition to my next CMS/Wiki:
[http://github.com/rcarmo/sushy](http://github.com/rcarmo/sushy) (already
supports Textile, Markdown and ReST).

~~~
riffraff
the first wiki I wrote used textile, I added wikipedia-style links and it was
about perfect. I still can't understand why markdown overtook it in
popularity.

------
cies
Alternatives: asciidoc.

Maps easily to docbook, and has a heap of extra features.

~~~
zimbatm
And it's also relatively close to markdown (biggest change is links).

The asciidoctor project also has browser extensions for rendering which are
really nice. For the lazy: [http://asciidoctor.org/](http://asciidoctor.org/)

~~~
k__
Github can render asciidoc. Do they use asciidoctor.JS?

I found the lib was rather big :/

------
lucb1e
Since getting ReText, a simple Markdown editor which can export to PDF, ODT
and HTML, I notice I want to make many documents in it instead of using
LibreOffice. As long as it doesn't need imagery but just normal text with
formatting (chapters, bullet points, perhaps code examples, etc.), it's much
easier to create and keep in version control. It's super light, in a text-
based format no program will ever have issues with (try the "open" docx format
in LibreOffice) and when sending it to others I just attach a pdf export.

Markdown as a spec may not be nailed down 100%, but as a practical thing to
use it's very handy. There are implementation differences between
StackOverflow and ReText, but those are details.

------
billpg
Markdown and all the other Markdown-esque formats need to be consigned to the
history books.

No really. It is almost 2015 and we are still typing _symbols_ on each side of
words in text boxes when we want to emphasize something. Are we cavemen?

(Following was added after initial posting)

Technology has moved on. We should no longer need to remember which
combination of magic symbols we need to make a bulleted list or whatever.

There are often helpers to insert those magic symbols. That's great, but then
why keep showing us the magic symbols? Do you want me to care that _s
represent italics? Will including this second_ cause this fragment to be
italicized? How do you show an asterisk without it meaning intalics? Grrr...

~~~
wtbob
> It is almost 2015 and we are still typing symbols on each side of words in
> text boxes when we want to emphasize something.

That's called markup. It's what HTML is; it's what any plain-text format is.
And it's a good thing: it's interchangeable and archiveable.

~~~
billpg
HTML is great, mostly because it actually does the job and knows its place.

Markdown and their ilk are all trying to be sorta-not-quite-HTML, but fail
precisely because they are not HTML.

------
ilchenearly
To me, one big issue is that you cannot use markdown to present everything,
for example, one cannot use it to produce something like <pre>`d`<pre>, I mean
he cannot use ``d`` to do that, right? Also you cannot write

```

```markdown

## HEADER

```

```

to produce a fenced code block which contains a markdown source code for code
block.

Also, different markdown editor use different markdown parser. So, same source
code will be rendered differently in different editor.

------
cespare
Can we get a (2012)?

------
shurcooL
Markdown is many different things to many people. I love Markdown, but I mean
the GitHub Flavored Markdown. Using plain Markdown would be very weird for me.
So discussing flaws of plain Markdown seems pointless to me since I don't use
it due to a much better variant being available.

------
arh68
Does anyone else prefer txt2tags [1]? It also works.

[1] [http://txt2tags.org/features.html](http://txt2tags.org/features.html)

~~~
cogburnd02
I do; of all the lightweight markup languages, it seems like only txt2tags has
a sane representation of HTML links. [1]
[http://en.wikipedia.org/wiki/Lightweight_markup_language#Lin...](http://en.wikipedia.org/wiki/Lightweight_markup_language#Link_syntax)

~~~
JetSpiegel
Ugh, that's the syntax of TVTropes. What a mess, I never know if the title
comes before or after the link, and whether to wrap with 1 or 2 square braces.

~~~
cogburnd02
[ @JetSpiegel ] Challenge:

(1) write an 8-page (or more) document with 32 (or more) hyperlinks in it in
both txt2tags and any other format.

(2) Print out the plain-ASCII source files.

(3) Wait until you forget the whole text of what you've written.

(4) Re-read it (both versions) somewhere without access to a
computer/phone/tablet. (e.g. the bathroom)

You will understand why txt2tags makes more sense:

(1) Less markup [i.e. fewer characters] than Markdown, Textile/Texy, AFT, reST

(2) Text-first, unlike AsciiDoc, MediaWiki, PmWiki, Org-Mode, BBCode. Text-
first leads to better/easier readability of source ASCII IM(NSH)O.

(3) Unlike POD, has a syntax for named links.

------
jrochkind1
2 years later, how's creole doing, anyone know? Has it developed (in any sense
of the word) much in two years?

------
1wd
Yes, Markdown is really bad. I really wonder why it's so much more popular
than Creole, Textile etc.

~~~
archagon
Revisit your starting assumption?

~~~
Turing_Machine
It looks like the famous Bjarne Stroustroup quote holds true for markup
languages as well as programming languages.

"There are only two kinds of languages: the ones people complain about and the
ones nobody uses."

------
buster
This article is great. I really never understood the preference of Markdown
over rST. Also, little do people know that github supports rst
[https://github.com/github/markup](https://github.com/github/markup)

But looks like Creole as well, which i didn't know :)

~~~
aidenn0
As far as I can tell the only advantage rST has over markdown is that it's
better defined. I rarely find that I prefer the rST syntax to markdown.

~~~
buster
I frequently write documentation with sphinx, over 30 pages long. rST is a
blessing for me. Markdown doesn't even get near.

It's fine for some 20 line README on github but that's about it.

~~~
aidenn0
I'm with you there in that I couldn't imagine writing 30 pages of markdown.
For something like extensive documentation, I could imagine rST winning,
particularly since there is a standard syntax for extending it.

I still mostly use LaTeX for documentation though.

~~~
buster
You should give sphinx + latex a try. I have my own cookiecutter template for
docs and it's never been easier and fast to write some good looking documents.

------
anonymfus
wikicreole.org don't work without www. Right link is
[http://www.wikicreole.org/](http://www.wikicreole.org/)

~~~
bigbugbag
That's what I came to the comments for.

wikicreole webmaster, please do configure your DNS thoughtfully, and OP please
check your links before posting.

