Support GitHub's Alert Markdown extension

[chlorine3545]

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.

[chlorine3545]

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>

[chlorine3545]

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)

[jakeprice-me]

I've been trying this out following the new documentation and it works great, thanks to @bep and @jmooring.

I have however noticed that the alert type's seem to be hardcoded to only accept a few preset types (the five mentioned in GitHub's alerts documentation) - which makes sense because this ticket was for exactly that!

However, it would be quite helpful if we could define additional alert types. I use Obsidian and this change is great because Obsidian does alerts the same way as GitHub, but supports a few more alert types, see here for the list (stuff like info, danger etc).

Would @bep consider adding functionality to allow the user to manually define their own alert types in config.yml?.

[jmooring]

@jakeprice-me Please open a new issue.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.