x/pkgsite: render mermaid js about go

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

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

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

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

[nnzv]

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

[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/[email protected]/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' });
})();

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

[AlexanderYastrebov]

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