x/pkgsite: support markdown alerts in readme

fxamacker commented 2 weeks ago

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/docker/buildx#section-readme

What is your user agent?

All user agents

[!NOTE]

This issue affects all web browsers.

GitHub introduced markdown alerts in 2023 as an extension to GfM (2019).

Screenshot

Got unformatted alerts (e.g. [!WARNING]) at https://pkg.go.dev/github.com/docker/buildx#section-readme:

Got formatted alerts on GitHub at https://github.com/docker/buildx:

What did you do?

View projects using markdown alerts like github.com/docker/buildx on pkg.go.dev.

Or use any of these GitHub markdown alerts in a README.md.

> [!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.

What did you see happen?

Markdown alerts are not formatted as alerts at pkg.go.dev.

For example, [!WARNING], [!IMPORTANT], and [!NOTE] alerts are not formatted as alerts.

What did you expect to see?

Expected to see markdown alerts formatted as alerts. GitHub documentation lists these alerts:

[!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.

EDIT: Added note that GitHub introduced markdown alerts in 2023 as an extension to GfM (2019). Also clarified and reordered screenshots.

adonovan commented 2 weeks ago

@matloob What level of GfM compatibility does pkgsite promise?

fxamacker commented 2 weeks ago

GfM was last updated in 2019. GitHub added markdown "alerts" syntax as an extension in 2023.

BTW, alerts can be used with <details> to expand their distinctive left border.

For example:

[!TIP] The example text (when expanded) is more clearly separate from nearby text.
This also works for code snippets with syntax highlighting.

Expandable lorem ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

This is useful for READMEs that have regular code snippets near expandable code snippets.

matloob commented 2 weeks ago

@adonovan As far as I know, we try to promise what's in the GFM spec.

We do also support GitHub emojis which aren't in the GFM spec, but are documented on the Writing on GitHub document.

But we don't support Math or the color model feature. Math does appear on the rsc.io/markdown todo list, and if it's added there we'd probably turn it on here.

The interesting thing about this feature is that the rest of the GFM features that we support are mappings of markdown to pretty simple html (or the emoji characters). But, from what I see looking at the rendered output on the GitHub website, the alerts require some CSS for the sidebar and svgs for the alert icons.

golang / go