[gorgoiler]

Very briefly on admonitions: there is nothing stopping you from adding them to markdown yourself:

    <warning>
    You _really_ shouldn’t
    play with matches, Debbie.
    </warning>

Later on in that document:

    <style>
    warning {
        display: block;
        color: red;
    }
    </style>

Which is a very long winded way of saying that you can use markdown for authoring actual content, and then use good old HTML for styling whatever else you want to.

Relying on asciidoc for styling elements like admonitions always felt like the wrong tool for the job. Like writing a Java generator in Perl, instead of just writing actual Java.

[ethanwillis]

This is both the power and "problem" with Markdown. The "promise" (I'd say) of Asciidoc in general versus Markdown is that it aims to truly be a standard.

Markdown itself comes (not even implicitly, but explicitly!) with the philosophy that there is no "true" standard. It's very flexible, very customizable, and does not aim for interop between implementations, for tooling, and so on.

Asciidoc tries to focus on being a Standard with a capital "S" so that the entire ecosystem around it can interop properly without implementation specific quirks/incompatibilities.

Both are good tools but with completely different philosophies. I learned all of this because I wanted to make a fast markdown parser in WASM directly. And at the same time I wanted to have a common way to put together a book to be published. What I learned quickly when trying to come at Markdown from a technical perspective is that there are dozens or more Markdown flavors and the idea of "Markdown" as a "general thing" isn't accurate, there's not even really a "core" shared between the variants/flavors. Which is in stark contrast to Asciidoc.

edit: A small aside, I also learned that a few publishers that focus on tech writing specifically use Asciidoc for their "publishing" workflows. So in that realm Asciidoc is practically useful to know.

[subpixel]

Key word is "few", which is why AsciiDoc is so frustrating to work with. Not on account of it's own shortcoming, but because so little activity is going on in the community to push it forward or to drive further support.

For example, if GitHub fully supported AsciiDoc, you'd see a lot more people considering it. But it's just not worth the headache to them, apparently.

[ethanwillis]

I have to fully agree with you unfortunately :\

[teknopaul]

While it's true markdown isnt a standard. What ever your tool does defines it. For source code docs converted to HTML or man pages you only have one build.

Common mark is a standard if you need one.

[thayne]

> What ever your tool does defines it

What if you have multiple tools that use different flavors of markdown? Even if you don't ever use multiple tools on the same input, you have to remember which syntax is allowed by which tool.

[microflash]

There's also a generic directive proposal[1] that enables admonitions, YouTube embeds, etc. With remark[2] plugins, markdown can be as extensible as you may need. Here's a sample plugin for admonitions[3] by yours truly.

[1]. https://talk.commonmark.org/t/generic-directives-plugins-syn...

[2]. https://github.com/remarkjs/remark

[3]. https://github.com/Microflash/remark-callout-directives

[bad_username]

Markdown parsing inside html is hit and miss. Obsidian won't do it, for example.

[Symbiote]

That assumes you are writing only HTML.

With Asciidoctor, we produce decent-looking PDF documentation as well as HTML.

[gorgoiler]

That’s a good point. I wrote an introduction to CS course in Asciidoctor. The pure Ruby prawn stuff for rendering PNGs into PDFs, which is done bit by bit, ended up being too slow for me. I had hacks for doing fast proof-copies with low resolution images, but it ends up being much easier rendering the source into HTML and the HTML into PDF. Faster, but also requires a lot of learning about CSS page breaking which I’m sure a PDF engine would just do automatically for me. Alas, no budget for Prince CSS was available.

[MilStdJunkie]

Your PDF options in Asciidoc boil out to this:

Asciidoctor-pdf:: this is the Ruby prawn-based thing, it's the current official path, but SVG and images can choke it. Complex customization means extensions, and that has its own overhead.

FOPUB aka docbook-xsl:: this is built in to the AsciidocFX dedicated editor, and uses the DocBook-XSL pipeline. Yeah, I know, it's XSL, but since DocBook has such a long tail there's a huge amount of customization that's possible, along with some docbook-only features like better indices, list of figures, etc. It's also very capable of chewing through thousand page books if it's in its own environment. But again, XSL.

asciidoctor-web-pdf:: this is the semi-experimental web based PDF tool, based on Paged.js, that uses the CMM Paged Media Module Level 3 (CMM PMM L3). I think this is built in to Antora now. This has the best promise, in my opinion, but it's still pretty raw, again, in my opinion. Bring your JS and your CSS hat. Chews through some huge amounts of memory . . ah wait, they fixed that.

After these you have DBLATEX, which uses DocBook->LaTeX as its typesetting, and you have the Haskell thing, and the wiki-2-PDF converter that's default in Visual Studio Code Asciidoctor extension. There's a few others that have largely stalled, like the packt build system for docx, but they're interesting. I still use the packt thing.

[eevilspock]

> Which is a very long winded way of saying that you can use markdown for authoring actual content, and then use good old HTML for styling whatever else you want to.

Why does Markdown bother to have * and ** markup? Why not just use "<i>", "<b>", "<em>" or "<strong>"?

1. An admonition is no more "just styling" than is Markdown emphasis or strong markup, exclamation points at the end of a sentence or bullet lists (why not just use commas and "and"?). Admonitions are semantic.

2. HTML is not the only output rendering for Markdown.

[gorgoiler]

Because the majority of writing is text and lists. Admonitions don’t hit the sweet spot of requiring any extra-HTML markup. You can simply mark block level elements up with blocks.

You pretty much do this anyway in asciidoc, just with extra steps.

[thayne]

If you want an admonition that looks good, and not just a red box, you'll need a bit more css than that. And probably need to include an inline icon.

Oh, and github strips out style tags, so it doesn't work there.

[gorgoiler]

Yeah, it was just an example really. Going down this route of argument, do you need to move from markdown to asciidoc for admonitions, or do you really just need a good stylesheet? I would argue that the markup helper and the styling can — and usually do — end up being separate from each other.