GitHub Flavoured Markdown

[kitswas]

Describe the bug

GitHub Flavoured Markdown now has alerts.
Alerts are not (yet) rendered by doxygen. 😢

Expected behaviour

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goals.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

should be rendered into the beautiful

Note

Useful information that users should know, even when skimming content.

Tip

Helpful advice for doing things better or more easily.

Important

Key information users need to know to achieve their goals.

Warning

Urgent info that needs immediate user attention to avoid problems.

Caution

Advises about risks or negative outcomes of certain actions.

Screenshots

To Reproduce

See above.

Version

Doxygen Version 1.10.0 (ebc57c6) on Ubuntu 22.04.3 LTS (jammy jellyfish) downloaded from https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.linux.bin.tar.gz

Stack trace

Additional context

[albert-github]

Interesting.

In doxygen we have already commands like \note, \warning etc.
When translating the markdown alerts to these commands like in:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.



\note
Useful information that users should know, even when skimming content.

\remark
Helpful advice for doing things better or more easily.

\warning
Urgent info that needs immediate user attention to avoid problems.

\attention
Advises about risks or negative outcomes of certain actions.

we get:

So for

• > [!NOTE] to \note
• > [!TIP] to \remark
• > [!WARNING] to \warning
• > [!CAUTION] to \attention

the default translation would already be pretty good (as the user can always add a custom css file (HTML_EXTRA_STYLESHEET) with updated settings.

For the > [!IMPORTANT] I don't think there is a direct doxygen command and thus should be added.
In the mock-up I translated > [!TIP] into \remark and I'm not sure whether or not this is correct (same accounts, but less, for > [!CAUTION])

From the documentation on GitHub (https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts):

Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information.

and

To add an alert, use a special blockquote line specifying the alert type, followed by the alert information in a standard blockquote. Five types of alerts are available.

[albert-github]

Note: Only lines with single initial blockquotes are allowed:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> > [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> > Key information users need to know to achieve their goals.

Note

Useful information that users should know, even when skimming content.

[!TIP]
Helpful advice for doing things better or more easily.

Important

Key information users need to know to achieve their goals.

[kitswas]

Can we have those tiny svg icons too?
They are terrific.

[albert-github]

This is up to the user, he can add them and add the SVG files (for light and dark mode!) to the definitions in the css and as extra files HTML_EXTRA_FILES.
I'm not sure we would be able to provide them anyway (copyright / license ?)

[albert-github]

I've just pushed a proposed patch, pull request #10616

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.11.0.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).