search

tommilligan / mdbook-admonish

A preprocessor for mdbook to add Material Design admonishments.
MIT License
173 stars 18 forks source link

Compatibility with GitHub and Pandoc #72

Open dave42w opened 1 year ago

dave42w commented 1 year ago

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 commented 1 year ago

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!