12 ms·

Somewhat related past discussion: https://news.ycombinator.com/item?id=41120254 https://news.ycombinator.com/item?id=41120254 Copying my thoughts from there w

Somewhat related past discussion: https://news.ycombinator.com/item?id=41120254 https://news.ycombinator.com/item?id=41120254 Copying my thoughts from there which haven't changed: >To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?" Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant. Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax. I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments. ***** My thoughts on strictly-defined XML-ish syntaxes are the same: they're harder for humans to read, write, and modify, which defeats the primary purpose and benefit of Markdown. Very few people have to write a Markdown parser. Many orders of magnitude more have to read and write Markdown. Optimize for them even if it makes writing the parser painful.

vbezhenar 7mo ago
HTML is valid markdown. So I'm not sure how you make oppose markdown and XML. XML is basically a subset of markdown. This is *valid* <ul> <li>*Mark*</li> <li>_down_</li> </ul> Markdown basically adds a whole layer of complexity upon HTML.
- Arainach 7mo ago
 If you're writing things like that in Markdown files (without being escaped in code blocks as HTML syntax examples), you're doing it wrong.
 - smahs 7mo ago
 Not wrong, perhaps a little weird. HTML is a first class citizen in the commonmark (spec)[https://spec.commonmark.org/0.31.2/#html-blocks https://spec.commonmark.org/0.31.2/#html-blocks].
 - Arainach 7mo ago
 "Wrong" does not necessarily mean "against the standard". It means "against common usage and good team practice" in this context. It's "allowed" to use raw pointers, malloc, and any number of things in C++ code. In general, if you do any of them in a modern codebase you're doing it wrong.
 - alpaca128 7mo ago
 Yes, it's obviously "against common usage" given HTML support exists specifically for less common features that Markdown does not support. Like tables, which are supported by some implementations but not all, and iirc not even all Markdown variants that support tables use the same syntax for them. The only way to be 100% sure is to use HTML. Of course you wouldn't do that if you just have the file on Github, but in general HTML is supported in Markdown for a reason.
 NetMageSCW 7mo ago
 But it is a bad reason that goes against the reasons for the creation of Markdown.
frizlab 7mo ago
There are other solutions which are as easy to read/write (if not more) and which are defined much better… Asciidoc comes to mind.
- Arainach 7mo ago
  "Better specified" doesn't mean better. A bunch of features doesn't mean better. Markdown is popular because it is simple. I have never had to teach anyone Markdown. They look at the file and immediately see what's going on and can copy the style. Occasionally someone may have to look up something like table syntax, but no one in my career or personal life has ever asked me to explain Markdown to them, which is rare for a technology that is so widely used. This has not been my experience with other markup languages.
  - frizlab 7mo ago
    Have you tried Asciidoc though? It is, IMHO, much clearer than markdown (YMMV, obviously), and exactly the same pros you gave of markdown can be said of Asciidoc. Bonus: It starts simple but can be used to do whole books if needed.
    - Arainach 7mo ago
      My experience is that Asciidoc very quickly gets into advanced syntax. If you introduce something with advanced functionality onto a team, soon enough someone's going to use pieces that others don't fully understand later. Now everyone touching the document has to understand includes and document metadata and whatever else someone added. Suddenly you have includes and cross-references and what used to be a document where you could read the raw non-rendered form linearly top to bottom is a confusing mess unless you render it. Markdown is almost always just as legible raw as rendered.
    - theSherwood 7mo ago
      It's great apart from the nested list syntax. It's quite noisy. I'd prefer if it supported indentation.

vbezhenar 7mo ago

HTML is valid markdown. So I'm not sure how you make oppose markdown and XML. XML is basically a subset of markdown. This is *valid* <ul> <li>*Mark*</li> <li>_down_</li> </ul> Markdown basically adds a whole layer of complexity upon HTML.

Arainach 7mo ago
If you're writing things like that in Markdown files (without being escaped in code blocks as HTML syntax examples), you're doing it wrong.
- smahs 7mo ago
  Not wrong, perhaps a little weird. HTML is a first class citizen in the commonmark (spec)[https://spec.commonmark.org/0.31.2/#html-blocks https://spec.commonmark.org/0.31.2/#html-blocks].
  - Arainach 7mo ago
    "Wrong" does not necessarily mean "against the standard". It means "against common usage and good team practice" in this context. It's "allowed" to use raw pointers, malloc, and any number of things in C++ code. In general, if you do any of them in a modern codebase you're doing it wrong.
    - alpaca128 7mo ago
      Yes, it's obviously "against common usage" given HTML support exists specifically for less common features that Markdown does not support. Like tables, which are supported by some implementations but not all, and iirc not even all Markdown variants that support tables use the same syntax for them. The only way to be 100% sure is to use HTML. Of course you wouldn't do that if you just have the file on Github, but in general HTML is supported in Markdown for a reason.
      - NetMageSCW 7mo ago
        But it is a bad reason that goes against the reasons for the creation of Markdown.

frizlab 7mo ago

There are other solutions which are as easy to read/write (if not more) and which are defined much better… Asciidoc comes to mind.

Arainach 7mo ago
"Better specified" doesn't mean better. A bunch of features doesn't mean better. Markdown is popular because it is simple. I have never had to teach anyone Markdown. They look at the file and immediately see what's going on and can copy the style. Occasionally someone may have to look up something like table syntax, but no one in my career or personal life has ever asked me to explain Markdown to them, which is rare for a technology that is so widely used. This has not been my experience with other markup languages.
- frizlab 7mo ago
  Have you tried Asciidoc though? It is, IMHO, much clearer than markdown (YMMV, obviously), and exactly the same pros you gave of markdown can be said of Asciidoc. Bonus: It starts simple but can be used to do whole books if needed.
  - Arainach 7mo ago
    My experience is that Asciidoc very quickly gets into advanced syntax. If you introduce something with advanced functionality onto a team, soon enough someone's going to use pieces that others don't fully understand later. Now everyone touching the document has to understand includes and document metadata and whatever else someone added. Suddenly you have includes and cross-references and what used to be a document where you could read the raw non-rendered form linearly top to bottom is a confusing mess unless you render it. Markdown is almost always just as legible raw as rendered.
  - theSherwood 7mo ago
    It's great apart from the nested list syntax. It's quite noisy. I'd prefer if it supported indentation.