4 ms·

The fact that we cannot standardize on extensions means that markdown feels inadequate for more technical documents. If just a free more restrictions means I ca

The fact that we cannot standardize on extensions means that markdown feels inadequate for more technical documents. If just a free more restrictions means I can easily add block annotations to everything, I will jump aboard immediately. That it is easier for parser writers is just a perk.

chungy 4y ago
I honestly don't get why Markdown became preferred in most projects over AsciiDoc.
- wnoise 4y ago
  Have you tried to parse it? Even the Swiss army knife of document formats, pandoc, only supports it as an output format.
- markstos 4y ago
  Because people know and like Markdown. It’s good enough so they don’t go looking for a replacement. Markdown is used enough that you are going to need to know the syntax. So a competitor doesn’t just have to better, it has to have enough additional merits to be worth learning in addition to Markdown.
  - nerdponx 4y ago
    AsciiDoctor and Org Mode both have substantial additional merits over Markdown, and have dedicated user bases. The problem nowadays is that of implementation availability.
- abathur 4y ago
  I suspect a lot of it's inertia from before the choice mattered or was actually reflected on (though I guess there are still plenty of projects changing). It's easy, most projects can satisfice with it, and people on the projects that can't satisfice with it may not think about markup enough to realize they're painting themselves into a corner until they have a big ballast of existing documentation to cope with? I've been fumbling around for how to convey signs that a project may need better tools (https://t-ravis.com/post/doc/what_color_is_your_markup/ https://t-ravis.com/post/doc/what_color_is_your_markup/) but it's been slow-going and I'm bearish on how well ~better-practices will spread.
- nerdponx 4y ago
  I think this is partly because AsciiDoc has broadly been tied to a single implementation, AsciiDoctor, without a spec, not even a sketch in a blog post like the original Markdown was. It's only recently that AsciiDoc has begun to think of itself as "a markup language" rather than "the markup language used by AsciiDoctor". A spec is apparently WIP. As for why it never gained the memetic popularity of Markdown that might have led to a different trajectory, that's harder to say. The One True Markdown is fundamentally much simpler than AsciiDoc, and consequently much easier to learn, easier implement in JavaScript for live rendering on the Web, and easier to extend with your own opinionated features. So I think it was easy and attractive for various platforms like Hacker News and Github to support it, and this I think had a snowballing network effect. Personally I love AsciiDoc and I think it's the future of technical writing and publishing. It's everything I wanted out of reStructuredText but without its fussy, non-composable syntax. However I don't think that future will become reality until a spec is published that is friendly to implementers other than AsciiDoctor.
  - chungy 4y ago
    AsciiDoctor is a second implementation that doesn't even fully compatibly implement the original specification. The original AsciiDoc is pretty well-specified, and it's mostly the plaintext markup of stuff that was intended to go to DocBook, with very little surprises from that. AsciiDoctor pretty much focused on a direct HTML translation and ignored the inconvenient parts. (Some of the inconvenient parts are deprecated syntax that while AsciiDoc's had a replacement for, I've written the old style for ~20 years and when GitHub tries to render a document with AsciiDoctor, oops; sometimes I'll change the document, sometimes I'll decide rendering on GitHub isn't important.)
- uvtc 4y ago
  > I honestly don't get why Markdown became preferred in most projects over AsciiDoc. I think the primary reason is because Markdown is prettier to read (and also secondarily because it's good enough). There are lots of markup formats, but markdown is probably the easiest on the eyes.
eslaught 4y ago
I mean, you can already do all of this (and more) in Pandoc's Markdown dialect, which is CommonMark-compatible. The main things you're getting here are sanding down some of the sharp corners that CommonMark has, in exchange for some uglier syntax if you actually care about the use cases those sharp corners enable. The point on standardization is sort of moot until Djot becomes big enough to be more than a single implementation. I'd be happy to see it get to that level, but I won't be waiting for it either since Pandoc Markdown is perfectly servicable as it is.
- gavinhoward 4y ago
  > The point on standardization is sort of moot until Djot becomes big enough to be more than a single implementation. I'm currently working on a second implementation, mostly because I want my docs to be dependency-free, but also for standardization of djot.

chungy 4y ago

I honestly don't get why Markdown became preferred in most projects over AsciiDoc.

wnoise 4y ago
Have you tried to parse it? Even the Swiss army knife of document formats, pandoc, only supports it as an output format.
markstos 4y ago
Because people know and like Markdown. It’s good enough so they don’t go looking for a replacement. Markdown is used enough that you are going to need to know the syntax. So a competitor doesn’t just have to better, it has to have enough additional merits to be worth learning in addition to Markdown.
- nerdponx 4y ago
  AsciiDoctor and Org Mode both have substantial additional merits over Markdown, and have dedicated user bases. The problem nowadays is that of implementation availability.
abathur 4y ago
I suspect a lot of it's inertia from before the choice mattered or was actually reflected on (though I guess there are still plenty of projects changing). It's easy, most projects can satisfice with it, and people on the projects that can't satisfice with it may not think about markup enough to realize they're painting themselves into a corner until they have a big ballast of existing documentation to cope with? I've been fumbling around for how to convey signs that a project may need better tools (https://t-ravis.com/post/doc/what_color_is_your_markup/ https://t-ravis.com/post/doc/what_color_is_your_markup/) but it's been slow-going and I'm bearish on how well ~better-practices will spread.
nerdponx 4y ago
I think this is partly because AsciiDoc has broadly been tied to a single implementation, AsciiDoctor, without a spec, not even a sketch in a blog post like the original Markdown was. It's only recently that AsciiDoc has begun to think of itself as "a markup language" rather than "the markup language used by AsciiDoctor". A spec is apparently WIP. As for why it never gained the memetic popularity of Markdown that might have led to a different trajectory, that's harder to say. The One True Markdown is fundamentally much simpler than AsciiDoc, and consequently much easier to learn, easier implement in JavaScript for live rendering on the Web, and easier to extend with your own opinionated features. So I think it was easy and attractive for various platforms like Hacker News and Github to support it, and this I think had a snowballing network effect. Personally I love AsciiDoc and I think it's the future of technical writing and publishing. It's everything I wanted out of reStructuredText but without its fussy, non-composable syntax. However I don't think that future will become reality until a spec is published that is friendly to implementers other than AsciiDoctor.
- chungy 4y ago
  AsciiDoctor is a second implementation that doesn't even fully compatibly implement the original specification. The original AsciiDoc is pretty well-specified, and it's mostly the plaintext markup of stuff that was intended to go to DocBook, with very little surprises from that. AsciiDoctor pretty much focused on a direct HTML translation and ignored the inconvenient parts. (Some of the inconvenient parts are deprecated syntax that while AsciiDoc's had a replacement for, I've written the old style for ~20 years and when GitHub tries to render a document with AsciiDoctor, oops; sometimes I'll change the document, sometimes I'll decide rendering on GitHub isn't important.)
uvtc 4y ago
> I honestly don't get why Markdown became preferred in most projects over AsciiDoc. I think the primary reason is because Markdown is prettier to read (and also secondarily because it's good enough). There are lots of markup formats, but markdown is probably the easiest on the eyes.

eslaught 4y ago

I mean, you can already do all of this (and more) in Pandoc's Markdown dialect, which is CommonMark-compatible. The main things you're getting here are sanding down some of the sharp corners that CommonMark has, in exchange for some uglier syntax if you actually care about the use cases those sharp corners enable. The point on standardization is sort of moot until Djot becomes big enough to be more than a single implementation. I'd be happy to see it get to that level, but I won't be waiting for it either since Pandoc Markdown is perfectly servicable as it is.

gavinhoward 4y ago
> The point on standardization is sort of moot until Djot becomes big enough to be more than a single implementation. I'm currently working on a second implementation, mostly because I want my docs to be dependency-free, but also for standardization of djot.