feat: add markdown alerts support

[Bigstool]

Add support for the following markdown alerts utilizing the Hugo blockquote render hooks:

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

With:

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

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

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

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

Preview:

Reference:
https://github.com/orgs/community/discussions/16925

Related:
#1085

[AiratTop]

Looks great! Waiting for merge

[tats-u]

GitHub made a foolish decision to set the caution color as red instead of yellow. Stack should not follow in their footsteps.

From: https://www.muirgraphics.com/2016/08/difference-life-death-choosing-right-safety-signal-words/

From: http://www.overheadlifting.org/understanding-safety-signs-and-overhead-lifting-equipment-hazards/

From: http://www.ishiimark.co.jp/s-label-top.html

• Make (it possible to set) color of Caution yellow vuejs/vitepress#4926
• https://github.com/orgs/community/discussions/16925#discussioncomment-13930919

GitLab, Redmine, Docusaurus, and Starlight (Astro) sets the caution color as yellow.

Docusaurus and Starlight provides "Danger" as the red alert.

[Bigstool]

@tats-u Fair point! I agree that GitHub’s color choices can be questionable. For this PR, my main goal is to focus on adding basic support for markdown alerts first, and leave further refinements for follow-ups.

This topic also seems to be actively discussed across different projects, with no clear consensus yet. For example, instead of using yellow for caution, GitLab seems to have swapped the orange and red colors between caution and warning. Docusaurus apparently substituted caution with danger, and Starlight substituted warning with caution. Different platforms adopt different mappings for caution and warning, which makes it difficult to settle on a single “correct” scheme at this stage. Given that, I’d prefer to keep this PR focused on implementing the core feature.

Additionally, the current code should also be quite easy to customize the colors or add new alert types later when needed.

[tats-u]

Docusaurus apparently substituted caution with danger

No, "warning" used to be red: https://docusaurus.io/docs/next/migration/v3#admonition-warning
"caution" has been yellow and was replaced with "warning" changed to yellow.

quite easy to customize the colors

Why don't you mention emojis here? They're hard-coded and can't be touched by CSS. "🚨" is more severe than "⚠️".

We should at least switch between GitHub's defected coloring/order and ISO's gold standard coloring/order by a simple configuration.

[Bigstool]

@tats-u

No, "warning" used to be red

I think this illustrates my point nonetheless.

Why don't you mention emojis here? They're hard-coded and can't be touched by CSS. "🚨" is more severe than "⚠️".

Please kindly refer to the corresponding file of this commit. Simply change the emojis there.

Once again, I agree that the color scheme discrepancy is a fair and reasonable point for further discussions in a follow-up. For this PR, I want to focus on the core implementation of this feature. Thanks again for bringing your insights.

[tats-u]

I don't think someone who just wants to use this theme would easily modify the code examples to assign the same icon to multiple notice types.

[Bigstool]

@tats-u
It might still be better than not having markdown alerts support at all. As I have mentioned multiple times, this PR focuses on the core implementation of the feature. Thank you for your constructive feedback.

[CaiJimmy]

Thanks! I have made some changes so that the icon and color are customisable

[CaiJimmy]

Regarding the discussion about the coloring, I agree that it is debatable. However, now that it's available for user customization via CSS variables, it's a little less critical.