Support GitHub's Alert Markdown extension

[yoghurtlee-thu]

I am currently immersed in the development of a new Hugo theme, which aims to provide users with a seamless experience when writing Hugo blogs using Obsidian. However, when it comes to Callout blocks like this:

Important

This is a Callout.

Things get stuck. While utilizing shortcodes and regex can be a workaround, it tends to be error-prone and lacks elegance.

Thus, I am curious whether the esteemed Hugo development team would consider enhancing the Markdown parsing engine to natively support GitHub-style Callouts.

Yours sincerely.

[bep]

When this was proposed/implemented at GitHub, I suggested they used markdown attributes instead (which is certainly more standard and something Hugo could easily support).

They chose not to listen to me. But you could, e.g:

```callout {level="warning" }
This is a warning.
```

And add a code render hook for it.

[yoghurtlee-thu]

When this was proposed/implemented at GitHub, I suggested they used markdown attributes instead (which is certainly more standard and something Hugo could easily support).

They chose not to listen to me. But you could, e.g:

```callout {level="warning" }
This is a warning.

And add a code render hook for it.

Thank you for your kind reply, @bep. Using markdown attributes is indeed a more Markdown-standard solution, and I will try it in my development. I might also come up with another solution for our Obsidian users to write with ease.

I won't close this issue, and if there are any breakthroughs, I will update it.

Have a day as amazing as you are :)

[jmooring]

GitHub's documentation for their Alert Markdown extension:
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

GitHub's implementation is OK if you speak English. But for the rest of the planet, not so much.

Using English words in the alert designator (e.g., [!NOTE]) is fine, but the rendered alert type is always English. For example:

> [!NOTE]  
> Das ist meine Notiz.

Note

Das ist meine Notiz.

The above is just... rude.

We could support this monolignual syntax with a Goldmark extension, or (preferably) provide multilingual support via a blockquote render hook.

The blockquote render hook would parse the first line, looking for an alert designator (e.g., [!something]), and provide this context to the render hook template:

• .Attributes -- The Markdown attributes, if any.
• .Text -- The blockquote text.
• .PlainText -- The blockquote text as plain text.
• .Page -- A reference to the current page.
• .Ordinal -- The zero-based ordinal of the blockquote on the page.
• .Position -- The position of the blockquote within the page content.
• .IsAlert -- Returns true if the blockquote has an alert designator.
• .AlertType -- The alert type converted to lowercase.
• .AlertText -- The blockquote text, excluding the alert designator.
• .AlertPlainText -- The blockquote text as plain text, excluding the alert designator.

Ordinal and position are desired but not required. The ordinal is handy for assigning element ids, and the position is handy for error reporting. Example render hook:

{{ $emojis := dict
  "caution" ":exclamation:"
  "important" ":information_source:"
  "note" ":information_source:"
  "tip" ":bulb:"
  "warning" ":information_source:"
}}

{{ if .IsAlert }}
  <blockquote class="alert alert-{{ .AlertType }}">
    <p class="alert-heading">
      {{ transform.Emojify (index $emojis .AlertType) }}
      {{ or (i18n .AlertType) (title .AlertType) }}
    </p>
    {{ .AlertText | safeHTML }}
  </blockquote>
{{ else }}
  <blockquote>
    {{ .Text | safeHTML }}
  </blockquote>
{{ end }}

This render hook implementation would also allow you to do things like:

[markup.goldmark.parser.attribute]
block = true

> Some text
{cite="https://gohugo.io" caption="Some caption"}

<figure>
  <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}>
    {{ .Text | safeHTML }}
  </blockquote>
  {{ with .Attributes.caption }}
    <figcaption class="blockquote-caption">
      {{ . | safeHTML }}
    </figcaption>
  {{ end }}
</figure>

[yoghurtlee-thu]

Have there been any breakthroughs here? I wrote a Python script for an All-in-One regex and S3 image upload, and it works well for me for now. However, I'm still hoping for native support for GitHub alerts. This Markdown syntax does have its quirks, but it's currently the most widely used format. :)

PS: My hastily-written Python regex

alert_pattern = re.compile(r'^>\s*\[!(.*?)\]\s*\n((?:>.*\n)*)', re.MULTILINE | re.DOTALL)
def replace_alert(match):
    alert_type = match.group(1).strip()
    content = match.group(2).replace('>', '').strip()
    return f'{{{{< alert "{alert_type}" >}}}}\n{content}\n{{{{< /alert >}}}}'
    
content = alert_pattern.sub(replace_alert, content)