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.