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.
I really like that I can have the source file broken up over several lines but that it still defines a semantic "paragraph" that is rendered properly when convert to HTML or Latex.
If it respected single newlines, then I'd feel compelled to avoid newlines, but I'm trained too strongly on respecting column-formatted text files (though I don't stick religiously to the 72 or 80 char limit), so this would be a problem for me.
yes, it can be unintuitive, but single newline ignorance has its advantages too, for example one can make semantic line breaks[1] for easier diffability.
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.
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.
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"
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.
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/) 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.
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.
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.
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"...
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.
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.
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
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.
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.)
a) covers so little that every implementer feels a need to put their own conflicting extensions on it;
b) cannot be implemented consistently enough that one can be reasonably confident a document will probably render nearly-enough to not be described as 'broken' across engines;
and c) provides a "spec" in the sense of prose describing the author's intended meaning, but not a grammar or other formalization, test suite, etc. that can be considered authoritative for certifying that a given implementation is compliant (where compliant means that engines taking the same input will produce output close-enough to not be considered "broken" when compared to each other);
then your language probably sucks. Maybe it doesn't suck in the theoretical world where everything goes exactly as the language designer fantasizes, but it sucks in the actual world where people live and operate.
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.
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 "" 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.
> 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.
[+] [-] Aardwolf|7 years ago|reply
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|7 years ago|reply
Pre-formatted text is different. But that usually requires a separate context to make sure that all space stays in place, not just newlines.
[+] [-] radarsat1|7 years ago|reply
If it respected single newlines, then I'd feel compelled to avoid newlines, but I'm trained too strongly on respecting column-formatted text files (though I don't stick religiously to the 72 or 80 char limit), so this would be a problem for me.
[+] [-] indentit|7 years ago|reply
[1]: https://sembr.org/
[+] [-] leemailll|7 years ago|reply
[+] [-] manicdee|7 years ago|reply
[+] [-] vimslayer|7 years ago|reply
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|7 years ago|reply
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|7 years ago|reply
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/) 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|7 years ago|reply
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|7 years ago|reply
[+] [-] eeZah7Ux|7 years ago|reply
[+] [-] Jenkins2000|7 years ago|reply
The IntelliJ plugin is excellent.
And https://asciidoctor.org/docs/asciidoctor-diagram/ is amazing. I use PlantUML in it and love it.
[+] [-] romwell|7 years ago|reply
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/
[2]https://tiddlywiki.com/static/WikiText.html
[+] [-] cookiecaper|7 years ago|reply
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|7 years ago|reply
"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."
[+] [-] majkinetor|7 years ago|reply
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
[+] [-] indentit|7 years ago|reply
[+] [-] hestefisk|7 years ago|reply
[+] [-] Mikhail_Edoshin|7 years ago|reply
[+] [-] eudora|7 years ago|reply
I've heard of various implementations like kramdown and redcarpet behaving differently, so it seems that that is the case.
[+] [-] Fire-Dragon-DoL|7 years ago|reply
[+] [-] bdowling|7 years ago|reply
[+] [-] mrec|7 years ago|reply
[+] [-] amelius|7 years ago|reply
[+] [-] fxfan|7 years ago|reply
[+] [-] indentit|7 years ago|reply
[+] [-] thomasedwards|7 years ago|reply
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/
[+] [-] tkfu|7 years ago|reply
(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.)
[+] [-] cookiecaper|7 years ago|reply
a) covers so little that every implementer feels a need to put their own conflicting extensions on it;
b) cannot be implemented consistently enough that one can be reasonably confident a document will probably render nearly-enough to not be described as 'broken' across engines;
and c) provides a "spec" in the sense of prose describing the author's intended meaning, but not a grammar or other formalization, test suite, etc. that can be considered authoritative for certifying that a given implementation is compliant (where compliant means that engines taking the same input will produce output close-enough to not be considered "broken" when compared to each other);
then your language probably sucks. Maybe it doesn't suck in the theoretical world where everything goes exactly as the language designer fantasizes, but it sucks in the actual world where people live and operate.
[+] [-] louiechristie|7 years ago|reply
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|7 years ago|reply
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.
[+] [-] pjmlp|7 years ago|reply
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.