x/pkgsite: render mermaid js

[trajan0x]

What did you do?

Going to add feature request here.

While not formally included in the Github-Flavored Markdown Spec, Github supports mermaid diagrams

Given there's no good way to force these not to render on pkg.go.dev, but do render in readme's I think it'd be best if pkg.go.dev supported them.

I'll use one example from my project on how the ux can be sub-optimal otherwise.

We have a git-change-detector for go workspaces where a lot of the readme looks like this:

But on pkg.go.dev, it looks like this:

Anyway, would definitely be a nice to have

What did you see happen?

N/A

What did you expect to see?

N/A

[nnzv]

Supporting Mermaid.js in pkgsite would likely introduce unnecessary complexity and potential performance issues without significant benefits for Go developers.

[AlexanderYastrebov]

Maybe it makes sense to add codeblock language id to <pre>/<code> tags to enable userscript-based highlighting/rendering.

Update: this should actually work https://github.com/rsc/markdown/blob/0bf8f97ee8ef6dc359b2246680d8f48c37da77f1/code.go#L24-L39
maybe pkgsite uses old rsc.io/markdown version.

[gopherbot]

Change https://go.dev/cl/585955 mentions this issue: sanitizer: allow code block language class

[AlexanderYastrebov]

With the change https://go.dev/cl/585955 it should be possible to enable syntax highlighting and mermaid rendering via UserScript:

// ==UserScript==
// @name        pkg.go.dev syntax highlight
// @namespace   Violentmonkey Scripts
// @description Adds syntax highlighting to code blocks
// @match       https://pkg.go.dev/*
// @resource    css https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.css
// @require     https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js
// @require     https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js
// @grant       GM_addStyle
// @grant       GM_getResourceText
// @version     1.0
// @author      https://github.com/AlexanderYastrebov
// ==/UserScript==
GM_addStyle(GM_getResourceText("css"));
(function (){
    hljs.highlightAll();
    mermaid.initialize({ startOnLoad: false, theme: 'dark' });
    mermaid.run({ querySelector: '.language-mermaid' });
})();

[matloob]

I don't know if it's worth making the change in https://go.dev/cl/585955 if it's only going to be used by users who enable a custom script locally.

[zikaeroh]

Supporting Mermaid.js in pkgsite would likely introduce unnecessary complexity and potential performance issues without significant benefits for Go developers.

Given mermaid code blocks look like:

```mermaid
...
```

It seems reasonable to assume that the server/page could just not load mermaid code when there's no mermaid blocks, so I don't think this would have any overhead, no?

[AlexanderYastrebov]

I don't know if it's worth making the change in https://go.dev/cl/585955 if it's only going to be used by users who enable a custom script locally.

@matloob
What is the problem or risk to enable already existing codeblock language metadata?
Userscript is the straightforward usecase but there might be others like hints to the crawlers or corporate pkgsite deployments with syntax highlight by default.

[nnzv]

I don't know if it's worth making the change in https://go.dev/cl/585955 if it's only going to be used by users who enable a custom script locally.

Absolutely, that sounds like a more appropriate approach. By utilizing a script to generate necessary files from upstream sources, you can easily place the URL file where pkgsite can display it. This strategy enables flexibility with various tools, eliminating the need to confine yourself to just one option.

[adonovan]

We discussed this in our triage meeting and decided that the benefit of the feature is not worth the costs and risks. Go's pkg.go.dev site was never intended to fully simulate GitHub's markdown renderer.

[AlexanderYastrebov]

@adonovan @matloob What are the risks of adding a css class to the html element?

[adonovan]

@adonovan @matloob What are the risks of adding a css class to the html element?

The costs and risks of adding a class attribute are very low, though the value seems low also. I would not object to https://go.dev/cl/585955, though I defer to @matloob.

The feature I was referring to as "not worth the costs and risks" is the mermaid rendering that is the subject of this issue.