Compatibility with GitHub and Pandoc

[dave42w]

Hi,

I've just started using mdBook and have added mdBook-admonish. The look is great.

I am slightly concerned for the future when it comes to publishing my book in formats other than HTML. It looks like the mdBook renderers for PDF and EPUB are a long way from finished. So I was wondering about using PanDoc for more mature pdf and epub support.

However, I think I will need to get PanDoc to interpret my mdBook files as if they are GitHub flavoured Markdown as it doesn't support mdBook at present. GitHub seems to have standardised on

> **Note**
> This is a note

> **Warning**
> This is a warning

although that seems contentious. I see that CommonMark is also having discussions about what format to use and I see that this is also suggested as a "better" solution:

:::note
This is a note
:::

:::warning
This is a warning
:::

While Microsoft are apparently using

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

So the route of dBook-admonish of

```admonish quote
test quote
```

is unusual. Do you have any thoughts about supporting GitHub format or whatever Commonmark eventually decide on?

[tommilligan]

Hey, thanks for the suggestion/question. This crate currently uses pulldown-cmark for markdown parsing; so I would be very happy to support any syntax that's natively supported there (from the sound of it, this ::: syntax may be supported in the future?).

For now, supporting GitHub-flavor syntax seems doable, as it's just a combination of existing markdown syntax. However, this will be a subset of current functionality (can't handle e.g. custom titles).

It should also probably be opt-in with a new config option, we can remove this later if we think most users will want it.

If you'd like to work on a PR for supporting GitHub flavour markdown, I'm happy to review it. I may eventually implement it myself if not, but currently spare-time-coding is quite far down my list of things to do!

[daprilik]

I'm running into a related issue here, where I'd like to nest code blocks inside an admonishment, but the most natural way to do so doesn't work correctly (as you can't nest multiple triple-tick ``` blocks within one-another).

Having some alternative syntax for admonishments would be really useful.

It seems that pulldown_cmark does indeed have some optional opt-in ways to parse non-standard markdown syntax, which could maybe be co-opted for admonishments? https://docs.rs/pulldown-cmark/latest/pulldown_cmark/struct.Options.html

[tommilligan]

Hey, thanks for the feedback. Splitting up your points:

I'd like to nest code blocks inside an admonishment

The current way to achieve this is outlined here using existing markdown syntax, which allows 3 or more backtick/tilde characters to make a code block:

Option 1 (tildes):

~~~admonish bug
This syntax won't work in Python 3:
```python
print "Hello, world!"
```
~~~

Option 2 (more backticks):

````admonish bug
This syntax won't work in Python 3:
```python
print "Hello, world!"
```
````

Having some alternative syntax for admonishments would be really useful.

I'm not strictly opposed to new syntax for the blocks, but it does add code complexity/overhead as to how all the features are supported with each set of syntax. Basically I'd want to understand what you can't do conveniently with the existing syntax first.

It seems that pulldown_cmark does indeed have some optional opt-in ways to parse non-standard markdown syntax, which could maybe be co-opted for admonishments? https://docs.rs/pulldown-cmark/latest/pulldown_cmark/struct.Options.html

That does look doable, if you have a proposal for a syntax using them, I would be interested to hear it. Something like the +++ blocks is I presume what you're thinking of? Though to my eyes, this syntax looks strictly more limited than code blocks.

To be clear, this isn't something I will work on actively myself, but I'm happy to review/discuss with anyone who wants to work on it.

[daprilik]

Thanks for pointing out that alternate tile-based syntax! A bit embarassed that I missed that while reading through the mdbook-admonish guide 😅

I think that was the only major sticking point for me personally wrt. the need for alternate syntax.

[gabyx]

This issue should really be taken up as adherance to common syntax would not only be nice cause current codeblock stuff has major disadvantages etc

Cause tooling relies on this:

• breaks formatting: prettier cannot format stuff in code blocks...
• adhers to pandoc and other tooling which makes traversing to/from pandoc easier etc.
• linters dont work etc...

The best syntax is the correct pandoc Div syntax:

:::note
This is a note
:::

or even more aligned to pandoc

:::{.note style="font-size:10pt;" id="blabla" .my-other-class}

:::

• Also: attributes are probably best delimited with spaces as pandoc does:
  https://pandoc.org/MANUAL.html#extension-attributes.

@tommilligan I could work on this if you could show me where I could hook into the code and get started.

[tommilligan]

adherance to common syntax

@gabyx thanks for your comments - I think this is slightly different from the issue above, which is about various markdown syntax variations. I think I'm right in saying that your main points are that mdbook-admonish should use pandoc syntax instead?

mdbook-admonish is a plugin to mdbook which doesn't use pandoc at all, so I don't think there's a "common syntax" to adhere to in this setting. mdbook-admonish currently uses CommonMark syntax, which does not support ::: divs. While I appreciate as a pandoc user it would be more convenient for you to use pandoc syntax and tooling, I don't really see a reason to add it to this project specifically.

My guess would be that if pandoc-native syntax is desired, this would be better off as a pandoc-admonish plugin, but I don't know how the pandoc ecosystem functions; feel free to correct me here. If that is the case, I'd support factoring out some common api that both plugins can share.

[gabyx]

Your Argumentation is sound, however the plugin should be outside the scope of the commenmark spec anyway, since misusing a code block for this is just syntactically wrong or kind of a hack which works but is ugly.

There are syntaxes as mentioned which are not commonmark (yet) and since pandoc is the driver for the commonmark spec I am still on thw opinion using a codeblock is bad.

I know that markdown is heavily diversified and its hard to find a common ground except the markdown parsing pandoc supports which still is somewhat a corner stone in the landscape of markdown parsing etc. Its a sad place.

[gabyx]

related: lambdalisue/rs-mdbook-alerts#17 (comment)

[tommilligan]

You make good points - I misremembered that the parser we use was linked to mdbook internals somehow, rather than being completely uncoupled, so actually there's nothing preventing us swapping it out. Also I was unaware pandoc was a driver for a lot of commonmark stable features, so thanks for pointing that out.

I think it should be fine in that case to replace the pulldown_cmark parser with a another parser, and plumb the output in appropriately. The existing code block syntax can be supported back compatibly, while supporting div syntax as well. This assumes the new parser has a superset of the old one's functionality.

Assuming the new parser you want to add is pandoc itself, the downside of this would be introducing a dependency on having pandoc installed and available at runtime. Currently the parser is bundled with the plugin installation itself. I'd suggest in that case we gate this behind a pandoc feature flag, and keep the existing parser as is when this flag isn't enabled.

I think the easiest way to point out where to get started is to write a draft PR with some comments - I can do that this week.

[tommilligan]

@gabyx please see #231 as a rough starting point for plugging in pandoc as an alternative parser.