7 ms·

Why Markdown Sucks (2016)

51 points by MilnerRoute 8y ago

romwell 8y ago
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
- cookiecaper 8y ago
  The post complains that markdown engines render supposedly-the-same-thing in ways different enough to constitute breakage, and that neither engine in question uses a formal grammar to indicate how the language is parsed, making translation between the two very difficult. The complaint is not actually about any kind of syntax at all -- he mentions that pen and paper is his favorite alternative -- but rather the language's ability to yield consistent and reliable results across different implementations.
- acqq 8y ago
  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 8y ago
    >"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 8y ago
      > Is that possible for any program to do it in plaintext? Sure, TeX.
      - leemailll 8y ago
        The above quote mentioned the quoted one wants to take full control of character position, is this achievable with plain TeX?
        NikkiA 8y ago
        Yes, but it'd be painful.
hestefisk 8y ago
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 8y ago
  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.
thomasedwards 8y ago
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 8y ago
 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 8y ago
 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 8y ago
 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 specify the grammar.
 - joeblau 8y ago
 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.
- 8y ago
Aardwolf 8y ago
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.
- leemailll 8y ago
  It actually comes from plaintext emails. If you read emails like that a lot in a terminal you might agree a blank line between paragraphs will ease the reading.
- phicoh 8y ago
  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 8y ago
    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?
carlmr 8y ago
AsciiDoc is pretty good because it's similar enough and standardized better. Also more extensible, yet a bit more complicated to get running.
- eeZah7Ux 8y ago
  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 8y ago
    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.
- Jenkins2000 8y ago
  AsciiDoc is also supported by GitHub, I just use README.adoc instead of README.md. The IntelliJ plugin is excellent. And https://asciidoctor.org/docs/asciidoctor-diagram/ https://asciidoctor.org/docs/asciidoctor-diagram/ is amazing. I use PlantUML in it and love it.
fxfan 8y ago
Neither markdown nor any of the other light weight marktup languages mentioned here (so far and likely till expiry) can do numbered lists ;)
- indentit 8y ago
 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 8y ago
 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 8y ago
 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.
 - enriquto 8y ago
 Notice that in HTML5 you do not need to close the li tags
 - 8y ago
indentit 8y ago
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"...
louiechristie 8y ago
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.
- pjmlp 8y ago
 > 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? That is exactly what I have done at several occasions at customers that made use of either Docbook or DITA, with graphical tooling like Oxygen XML, Framemaker, DITAworks and so on.
- lmm 8y ago
 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 "blah blah", 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. "" and "" do the exact same thing but you're supposed to use "" because it's "more semantic" - apparently screenreaders don't understand "" 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.
amelius 8y ago
The proof of a markup language is if you can document itself in it without too much problems.
bdowling 8y ago
Markdown sucks because the lowest level headings, the ones you use most often, require the most typing of #s.
- mrec 8y ago
  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 8y ago
    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.
    - krilly 8y ago
      Meaning that if you start off by writing all your top level headings like a normal human being, you'll have to go back and change every single heading once you realise you need a h6?
    - mrec 8y ago
      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.
    - zaarn 8y ago
      Atleast in most common use, markdown parsers aren't that smart. They don't do much lookahead, they parse text in a stream with little buffering. The most complex behaviour is tables, and even there you can easily spot where the parsers simply go character by character along the line with no difference other than being in "table mode" (or for code fences, in "code mode")
vimslayer 8y ago
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 8y ago
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.
majkinetor 8y ago
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
eudora 8y ago
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.
coldtea 8y ago
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.
wallstprog 8y ago
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.
Fire-Dragon-DoL 8y ago
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

51 points by MilnerRoute 8y ago

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

cookiecaper 8y ago
The post complains that markdown engines render supposedly-the-same-thing in ways different enough to constitute breakage, and that neither engine in question uses a formal grammar to indicate how the language is parsed, making translation between the two very difficult. The complaint is not actually about any kind of syntax at all -- he mentions that pen and paper is his favorite alternative -- but rather the language's ability to yield consistent and reliable results across different implementations.
acqq 8y ago
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 8y ago
  >"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 8y ago
    > Is that possible for any program to do it in plaintext? Sure, TeX.
    - leemailll 8y ago
      The above quote mentioned the quoted one wants to take full control of character position, is this achievable with plain TeX?
      - NikkiA 8y ago
        Yes, but it'd be painful.

hestefisk 8y ago

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 8y ago
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.

thomasedwards 8y ago

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 8y ago
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 8y ago
 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 8y ago
 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 specify the grammar.
 - joeblau 8y ago
 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.
8y ago

Aardwolf 8y ago

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.

leemailll 8y ago
It actually comes from plaintext emails. If you read emails like that a lot in a terminal you might agree a blank line between paragraphs will ease the reading.
phicoh 8y ago
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 8y ago
  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?

carlmr 8y ago

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

eeZah7Ux 8y ago
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 8y ago
  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.
Jenkins2000 8y ago
AsciiDoc is also supported by GitHub, I just use README.adoc instead of README.md. The IntelliJ plugin is excellent. And https://asciidoctor.org/docs/asciidoctor-diagram/ https://asciidoctor.org/docs/asciidoctor-diagram/ is amazing. I use PlantUML in it and love it.

fxfan 8y ago

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

indentit 8y ago
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 8y ago
 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 8y ago
 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.
 - enriquto 8y ago
 Notice that in HTML5 you do not need to close the li tags
 - 8y ago

indentit 8y ago

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"...

louiechristie 8y ago

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.

pjmlp 8y ago
> 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? That is exactly what I have done at several occasions at customers that made use of either Docbook or DITA, with graphical tooling like Oxygen XML, Framemaker, DITAworks and so on.
lmm 8y ago
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 "blah blah", 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. "" and "" do the exact same thing but you're supposed to use "" because it's "more semantic" - apparently screenreaders don't understand "" 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.

amelius 8y ago

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

bdowling 8y ago

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

mrec 8y ago
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 8y ago
  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.
  - krilly 8y ago
    Meaning that if you start off by writing all your top level headings like a normal human being, you'll have to go back and change every single heading once you realise you need a h6?
  - mrec 8y ago
    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.
  - zaarn 8y ago
    Atleast in most common use, markdown parsers aren't that smart. They don't do much lookahead, they parse text in a stream with little buffering. The most complex behaviour is tables, and even there you can easily spot where the parsers simply go character by character along the line with no difference other than being in "table mode" (or for code fences, in "code mode")

vimslayer 8y ago

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 8y ago

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.

majkinetor 8y ago

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

eudora 8y ago

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.

coldtea 8y ago

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.

wallstprog 8y ago

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.

Fire-Dragon-DoL 8y ago

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