Add GitHub callouts documentation

[blackstream-x]

Description

Hi,
first of all, thank you for your great work!

I am unsure if this is the correct place, but as a followup to zensical/zensical#688 I think it would be very nice to have an example, maybe on the admonitions page, pointing out how GitHub style callouts can be used in Zensical (and where the pitfalls lie)

Related links

• Reporting a docs issue
• Admonitions page

Proposed change

No response

Before submitting

• I have read and followed the documentation issue guidelines.
• I have attached the links to the affected sections of the documentation

[squidfunk]

Thanks for the suggestion! Since it's a pure Markdown extension, it will work just out of the box, so we can just mention it in the admonitions section @alexvoss

[blackstream-x]

Tip

what I noticed:

1. [!NOTE], [!TIP] and [!WARNING] work as expected, [!CAUTION] and [!IMPORTANT] render as default (like [!NOTE]), more precisely: all keywords render like Zensical standard admonitions (https://zensical.org/docs/authoring/admonitions/#supported-types).
2. Callouts with Keywords in lower case are rendered (as they are in GitHub as well) , but always trigger an "unresolved link reference" warning because only uppercase keywords are checked, The same applies to non-GitHub-defined keywords like ABSTRACT or DANGER.

[squidfunk]

Thanks for noting. We might consider adding native support for the two types in the future. In the time being, you can define your own admonition. This guide for Material for MkDocs also applies to Zensical. Callouts are not part of the GitHub Markdown Spec (GFM), and not natively supported by at least some GFM-compatible Markdown parsers.

Callouts with Keywords in lower case are rendered (as they are in GitHub as well) , but always trigger an "unresolved link reference" warning because only uppercase keywords are checked, The same applies to non-GitHub-defined keywords like ABSTRACT or DANGER.

That is correct. Syntax must be all uppercase, or it's not rendered as a callout, which will fallback to a link reference. itHub doesn't render lowercase callouts as well.

[DevTwilight]

I got a custom admonition working in the modern theme variant using extra.css.

For anyone interested, here is the setup:

:root {
  --md-admonition-icon--important: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M5.52.359A.5.5 0 0 1 6 0h4a.5.5 0 0 1 .474.658L8.694 6H12.5a.5.5 0 0 1 .395.807l-7 9a.5.5 0 0 1-.873-.454L6.823 9.5H3.5a.5.5 0 0 1-.48-.641z"/></svg>');
}

/* important admonition type */
.md-typeset .admonition.important {
  background-color: rgba(245, 158, 11, 0.1);
  border-color: rgb(245, 158, 11);
}

/* icon + title handling  */
.md-typeset .important > .admonition-title::before,
.md-typeset .important > summary::before {
  background-color: rgb(245, 158, 11);
  mask-image: var(--md-admonition-icon--important);
}

  !!! important
      Redirect URIs must exactly match what is configured in the provider dashboard, including scheme, host, path, and trailing slashes.

Admonition Preview