5 ms·

Every time I see people doing something with Markdown, I wish they just replace it with support for Djot[0] instead. It is a Markdown alternative by the creator

by magnio 3y ago

Every time I see people doing something with Markdown, I wish they just replace it with support for Djot[0] instead. It is a Markdown alternative by the creator of Pandoc and CommonMark that fixes all of the most egregious mistakes, while being legible and visually pleasant as-is. It is also syntactically similar to Markdown, which should ease adoption. [0] https://github.com/jgm/djot https://github.com/jgm/djot

James_K 3y ago
Why not just HTML?
- rmbyrro 3y ago
  Too verbose for some applications is one reason not
- bluGill 3y ago
  Too annoying to write by hand. also too annoying to read the raw text. Markdown is easy to write by hand and looks good enough without a viewer.
  - enriquto 3y ago
    Apart from the p tag, that gets annoying when you have long stretches of prose, I find plain html5 much less annoying than markdown. Moreover, tables and hyperlinks are clearer and easier to type in html5 than in any markdown flavor.
    - subtra3t 3y ago
      Easier to type? Sure, but I don't think HTML5 tables are easier to read than markdown tables
      - enriquto 3y ago
        Thanks to optional closing tags, html5 tables are quite neat: <table> <tr> <td>first row, first column <td>first row, second column <td>first row, third column <tr> <td>second row, first column <td>second row, second column <td>second row, third column </table> Does it get any better in markdown?
        eviks 3y ago
        The fact that you need to list columns in rows already makes it NOT a table
        bluGill 3y ago
        Both are diffult to read and work with.
        eviks 3y ago
        both are difficult to work with since it's not the job of a data format, but table editing tooling on top of that, but the markdown tables that look like tables aren't difficult to read unlike HTML
        subtra3t 3y ago
        I'll convert your example to GFM. | first row, first column | first row, second column | first row, third column | | ------------------------ | ------------------------- | ------------------------ | | second row, first column | second row, second column | second row, third column | To me, this is more readable than the HTML version.
        kotborealis 3y ago
        It's not fun to manually reformat those tables for readability. If I add something to the `second row, second column`, I have to add extra spaces to the `first row, second column`, or it will look janky. | first row, first column | first row, second column | first row, third column | | ------------------------ | ------------------------- | ------------------------ | | second row, first column | exceptionally long second row, that makes second column look worse | second row, third column |
  - James_K 3y ago
    This is an eminently solvable problem. I've been writing my personal website in a variation of HTML for a while now which is perfectly easy to write and read. {main {h1 Title} {p Paragraph 1. {{a {href google.com}} Here is a link.}} {p Paragraph 2, now with {b bold} text.}} The nice thing about HTML/XML is that it's a clear data-structure, so you can essentially read it in any format you like and convert that to the underlying tree structure without much issue. That's why it's been so successful, basically the same philosophy as a lisp. Why someone would look at that and think "let's go back to a document with no clear structure" is beyond me.
    - lelanthran 3y ago
      You solved it with s expressions. Replace the braces with parens and you can parse that into a tree with only a handful of lisp macros.
      - James_K 3y ago
        The braces are quite deliberate. Firstly, parens are used often in writing and it would be a pain to have to escape them. Secondly, it integrates much easier with the Scheme code of my site generator this way. I can write in a file, something like: (define (code-block file-name) {pre {{code {class block}} #(cmd "highlight" (thisdir (string-append "posts/" file-name)) "-O" "html" "--inline-css" "--fragment" "--line-numbers" "--line-number-length" "3")}}) And it fits quite nicely with surrounding code. The mapping of these curly expressions to Scheme ones is relatively simple, though there is a special case for joining words to brackets. {a {b} #c #@d} => `("a" ("b") ,c ,@d) {a {b}c} => `("a" ("b") join "c")
        lelanthran 3y ago
        Sure, I didn't mean to imply that you didn't know what you were doing. I was just adding more context for those readers who don't know what an s-expression is. FWIW, my first static blogging system (circa 2003) did almost exactly the same thing you are doing (except that I used `[]` for lists, not `{}`). IIRC, it was maybe 5-6 macros+functions (and some readtable magic) to turn every `[foo ...]` into `<foo> ... </foo>`, with support for attributes using `:name=value` syntax and a list of exceptions for non-closing tags such as `<br>`, etc. I redid something like that recently, in C, and it turned out to be unreasonably larger to write than in Clisp. TBH, these days it's better to simply stick to markdown, because the tooling is much better (previews as you type, tools to automatically generate the html, inline HTML for what markdown won't do, etc).
- perpil 3y ago
  Markdown lacks prompting for inputs and running javascript but is easier to write and offers a quicker update, preview, deploy cycle. Preview and deploy is often a simple save vs. a build and deploy process. By extending markdown to support prompting for inputs and running javascript, you close some of the gaps and get the best of both worlds.
- ravenstine 3y ago
  It depends on the intent. Markdown is meant to be readable on its own. If you don't plan on reading Markdown files in some sort of plain text editor, then the benefit of Markdown is greatly diminished. Also, no one has implemented a really good experience for writing HTML, not for webpages, but simple documents. It could be really easy to write HTML mostly by hand if an editor could dynamically convert Markdown-like syntax into HTML tags on the fly. That way, the resulting document is definitely HTML, and not up to the interpretation of some flavor of Markdown. Such an editor can also do things to try and soft-preview what emphasis the HTML represents. Here's an example of an experiment I worked on in this direction a long time ago: https://codepen.io/Ravenstine/pen/gyMVNx https://codepen.io/Ravenstine/pen/gyMVNx ^^ Never mind the pompous attitude I had when I wrote the placeholder text for it.
eviks 3y ago
Unfortunately, not all, ignoring the linebreak is one of the most Not sure, but isn't using _ instead of the more intuitive /italics/ a big mistake on the syntax side?
- mst 3y ago
  Lots of things use underscore for italics, if you asked me to guess I'd certainly try it first (and asterisk for bold). ... in fact I just tried it and underscore apparently works in WhatsApp, TIL. OTOH /italics/ reads to me as a regular expression, which ... is apparently not what you meant. (as ever, "intuitive" varies wildly between people, and the trick is to pick the option that's intuitive for the highest possible percentage of your expected user base)
  - eviks 3y ago
    / intuition is pretty simple: slanted mark for slanted text What's that wild intuition of underscores??? Also, why would you ever read it as a regex in a human /text/ markup language?
    - mst 3y ago
      Underscores indicate emphasis, just like underlining would, but in text you usually get italics (I'd note that this is often an <em> tag so it being italics is a browser default style). Plus underscores get used -lots- of places for italics; I've yet to see the / form in the wild. A markup language being (as here) used for technical purposes can easily be interpreted according to geek writing conventions.
      - eviks 3y ago
        So the intuition for _ would be underlining! Pretty simple. Where would your intuition jump to for underlining in markdown if _ is italics? Em is just another bad term - which of the emphasis styles do you mean? Re popularity - so what? How does widespread bad turns into intuitive good? Bear notes used / for italics, also Orgmode (is that geek enough for you?)
bobbylarrybobby 3y ago
Why not just asciidoctor?
- deafpolygon 3y ago
  Why not XML?
  - MilStdJunkie 3y ago
    The laundry list of problems that can land in one's lap going down the road of XML publishing is considerable. Many are non-negotiable, particularly on git-based version control or on modern computing environments with locked down Java versions. It would be boorish of me to cite all of them, one after the other, so try this exercise instead: Using an XML specification of your choice, working from a simple desktop computer, and with no money for fifty thousand dollar "end-to-end publishing solutions", perform the following: publish a document that uses conditional processing to show two different outputs for two different audiences while using a shared set of document components. <kitchen_timer/> What did you end up using? Anything neat? I'm going to bet you don't find anything at all. The tooling in XML publishing is weird, locked down, horrible, or all three plus some. Plus a lot. So, even if we pretend XML publishing is the bee's knees, it loses the speed test, it can't work on vanilla computers/requires admin rights constantly, and new writers train up on Asciidoc, from zero, in four hours. At a glacial, defense-industry-standard-for-fifty-year-old pace. Git probably provokes more existential crises in training than the markup does. Nothing compared to the business side, of course, but this is the defense business, and it's all madness.
kspacewalk2 3y ago
Sadly there doesn't seem to be a Python implementation.
jonhohle 3y ago
When the markup’s first design goal is to be parsable in linear time (and then proceeds to have a bunch of rules to support that goal instead of flexibility for humans) I don’t think there is much chance of catching on as a general markup language. Markdown was originally a loose formalization of how people already wrote text only emails. It was how _people_ wrote, not how to optimize for the computer.
- civilized 3y ago
  It's not like all humans are born knowing how to read and write Markdown. A standard that is slightly less flexible or intuitive for (some) humans while enabling vastly more machine applications could be a win.
  - Shog9 3y ago
    Could be, but mostly isn't. This thread and others like it are always full of folks lamenting that some other markup language isn't as popular or well-supported or both, even though said language has more features, a better spec, and got there first. Maybe Markdown just hit the sweet spot. But I actually suspect it's something else: as soon as it's very convenient to have machines ingesting and producing a language, it becomes tempting to create tooling that is unnecessarily strict in what it will accept while at the same time spitting out markup that is unusually difficult for humans to read. A sort of specialized violation of the Robustness Principle. The most famous example of this was probably XHTML, but even HTML5 suffers from it. And so we end up with stuff like Markdown because HTML tooling is too hostile to work with directly, and AsciiDoc because DocBook XML is similarly awful. They don't have to be, but...
0x3444ac53 3y ago
I second this. I discovered Djot last year and it's been my preferred markdown ever since. Very extensible, easily parsable.

by magnio 3y ago

James_K 3y ago

Why not just HTML?

rmbyrro 3y ago
Too verbose for some applications is one reason not
bluGill 3y ago
Too annoying to write by hand. also too annoying to read the raw text. Markdown is easy to write by hand and looks good enough without a viewer.
- enriquto 3y ago
  Apart from the p tag, that gets annoying when you have long stretches of prose, I find plain html5 much less annoying than markdown. Moreover, tables and hyperlinks are clearer and easier to type in html5 than in any markdown flavor.
  - subtra3t 3y ago
    Easier to type? Sure, but I don't think HTML5 tables are easier to read than markdown tables
    - enriquto 3y ago
      Thanks to optional closing tags, html5 tables are quite neat: <table> <tr> <td>first row, first column <td>first row, second column <td>first row, third column <tr> <td>second row, first column <td>second row, second column <td>second row, third column </table> Does it get any better in markdown?
      - eviks 3y ago
        The fact that you need to list columns in rows already makes it NOT a table
        bluGill 3y ago
        Both are diffult to read and work with.
        eviks 3y ago
        both are difficult to work with since it's not the job of a data format, but table editing tooling on top of that, but the markdown tables that look like tables aren't difficult to read unlike HTML
      - subtra3t 3y ago
        I'll convert your example to GFM. | first row, first column | first row, second column | first row, third column | | ------------------------ | ------------------------- | ------------------------ | | second row, first column | second row, second column | second row, third column | To me, this is more readable than the HTML version.
        kotborealis 3y ago
        It's not fun to manually reformat those tables for readability. If I add something to the `second row, second column`, I have to add extra spaces to the `first row, second column`, or it will look janky. | first row, first column | first row, second column | first row, third column | | ------------------------ | ------------------------- | ------------------------ | | second row, first column | exceptionally long second row, that makes second column look worse | second row, third column |
- James_K 3y ago
  This is an eminently solvable problem. I've been writing my personal website in a variation of HTML for a while now which is perfectly easy to write and read. {main {h1 Title} {p Paragraph 1. {{a {href google.com}} Here is a link.}} {p Paragraph 2, now with {b bold} text.}} The nice thing about HTML/XML is that it's a clear data-structure, so you can essentially read it in any format you like and convert that to the underlying tree structure without much issue. That's why it's been so successful, basically the same philosophy as a lisp. Why someone would look at that and think "let's go back to a document with no clear structure" is beyond me.
  - lelanthran 3y ago
    You solved it with s expressions. Replace the braces with parens and you can parse that into a tree with only a handful of lisp macros.
    - James_K 3y ago
      The braces are quite deliberate. Firstly, parens are used often in writing and it would be a pain to have to escape them. Secondly, it integrates much easier with the Scheme code of my site generator this way. I can write in a file, something like: (define (code-block file-name) {pre {{code {class block}} #(cmd "highlight" (thisdir (string-append "posts/" file-name)) "-O" "html" "--inline-css" "--fragment" "--line-numbers" "--line-number-length" "3")}}) And it fits quite nicely with surrounding code. The mapping of these curly expressions to Scheme ones is relatively simple, though there is a special case for joining words to brackets. {a {b} #c #@d} => `("a" ("b") ,c ,@d) {a {b}c} => `("a" ("b") join "c")
      - lelanthran 3y ago
        Sure, I didn't mean to imply that you didn't know what you were doing. I was just adding more context for those readers who don't know what an s-expression is. FWIW, my first static blogging system (circa 2003) did almost exactly the same thing you are doing (except that I used `[]` for lists, not `{}`). IIRC, it was maybe 5-6 macros+functions (and some readtable magic) to turn every `[foo ...]` into `<foo> ... </foo>`, with support for attributes using `:name=value` syntax and a list of exceptions for non-closing tags such as `<br>`, etc. I redid something like that recently, in C, and it turned out to be unreasonably larger to write than in Clisp. TBH, these days it's better to simply stick to markdown, because the tooling is much better (previews as you type, tools to automatically generate the html, inline HTML for what markdown won't do, etc).
perpil 3y ago
Markdown lacks prompting for inputs and running javascript but is easier to write and offers a quicker update, preview, deploy cycle. Preview and deploy is often a simple save vs. a build and deploy process. By extending markdown to support prompting for inputs and running javascript, you close some of the gaps and get the best of both worlds.
ravenstine 3y ago
It depends on the intent. Markdown is meant to be readable on its own. If you don't plan on reading Markdown files in some sort of plain text editor, then the benefit of Markdown is greatly diminished. Also, no one has implemented a really good experience for writing HTML, not for webpages, but simple documents. It could be really easy to write HTML mostly by hand if an editor could dynamically convert Markdown-like syntax into HTML tags on the fly. That way, the resulting document is definitely HTML, and not up to the interpretation of some flavor of Markdown. Such an editor can also do things to try and soft-preview what emphasis the HTML represents. Here's an example of an experiment I worked on in this direction a long time ago: https://codepen.io/Ravenstine/pen/gyMVNx https://codepen.io/Ravenstine/pen/gyMVNx ^^ Never mind the pompous attitude I had when I wrote the placeholder text for it.

eviks 3y ago

Unfortunately, not all, ignoring the linebreak is one of the most Not sure, but isn't using _ instead of the more intuitive /italics/ a big mistake on the syntax side?

mst 3y ago
Lots of things use underscore for italics, if you asked me to guess I'd certainly try it first (and asterisk for bold). ... in fact I just tried it and underscore apparently works in WhatsApp, TIL. OTOH /italics/ reads to me as a regular expression, which ... is apparently not what you meant. (as ever, "intuitive" varies wildly between people, and the trick is to pick the option that's intuitive for the highest possible percentage of your expected user base)
- eviks 3y ago
  / intuition is pretty simple: slanted mark for slanted text What's that wild intuition of underscores??? Also, why would you ever read it as a regex in a human /text/ markup language?
  - mst 3y ago
    Underscores indicate emphasis, just like underlining would, but in text you usually get italics (I'd note that this is often an <em> tag so it being italics is a browser default style). Plus underscores get used -lots- of places for italics; I've yet to see the / form in the wild. A markup language being (as here) used for technical purposes can easily be interpreted according to geek writing conventions.
    - eviks 3y ago
      So the intuition for _ would be underlining! Pretty simple. Where would your intuition jump to for underlining in markdown if _ is italics? Em is just another bad term - which of the emphasis styles do you mean? Re popularity - so what? How does widespread bad turns into intuitive good? Bear notes used / for italics, also Orgmode (is that geek enough for you?)

bobbylarrybobby 3y ago

Why not just asciidoctor?

deafpolygon 3y ago
Why not XML?
- MilStdJunkie 3y ago
  The laundry list of problems that can land in one's lap going down the road of XML publishing is considerable. Many are non-negotiable, particularly on git-based version control or on modern computing environments with locked down Java versions. It would be boorish of me to cite all of them, one after the other, so try this exercise instead: Using an XML specification of your choice, working from a simple desktop computer, and with no money for fifty thousand dollar "end-to-end publishing solutions", perform the following: publish a document that uses conditional processing to show two different outputs for two different audiences while using a shared set of document components. <kitchen_timer/> What did you end up using? Anything neat? I'm going to bet you don't find anything at all. The tooling in XML publishing is weird, locked down, horrible, or all three plus some. Plus a lot. So, even if we pretend XML publishing is the bee's knees, it loses the speed test, it can't work on vanilla computers/requires admin rights constantly, and new writers train up on Asciidoc, from zero, in four hours. At a glacial, defense-industry-standard-for-fifty-year-old pace. Git probably provokes more existential crises in training than the markup does. Nothing compared to the business side, of course, but this is the defense business, and it's all madness.

kspacewalk2 3y ago

Sadly there doesn't seem to be a Python implementation.

jonhohle 3y ago

When the markup’s first design goal is to be parsable in linear time (and then proceeds to have a bunch of rules to support that goal instead of flexibility for humans) I don’t think there is much chance of catching on as a general markup language. Markdown was originally a loose formalization of how people already wrote text only emails. It was how _people_ wrote, not how to optimize for the computer.

civilized 3y ago
It's not like all humans are born knowing how to read and write Markdown. A standard that is slightly less flexible or intuitive for (some) humans while enabling vastly more machine applications could be a win.
- Shog9 3y ago
  Could be, but mostly isn't. This thread and others like it are always full of folks lamenting that some other markup language isn't as popular or well-supported or both, even though said language has more features, a better spec, and got there first. Maybe Markdown just hit the sweet spot. But I actually suspect it's something else: as soon as it's very convenient to have machines ingesting and producing a language, it becomes tempting to create tooling that is unnecessarily strict in what it will accept while at the same time spitting out markup that is unusually difficult for humans to read. A sort of specialized violation of the Robustness Principle. The most famous example of this was probably XHTML, but even HTML5 suffers from it. And so we end up with stuff like Markdown because HTML tooling is too hostile to work with directly, and AsciiDoc because DocBook XML is similarly awful. They don't have to be, but...

0x3444ac53 3y ago

I second this. I discovered Djot last year and it's been my preferred markdown ever since. Very extensible, easily parsable.