x/website: code in README.md is excessively HTML escaped

[willfaught]

Go version

n/a

Output of go env in your module/workspace:

n/a

What did you do?

Go to https://go.dev/src/cmd/compile/internal/ssa/README

What did you see happen?

What did you expect to see?

v5 = Addr <*int> {~r1} v2

There appears to be a bug in the Markdown rendering. I can't repro it in VSCode Markdown preview. It might be an issue with the nearby asterisk.

[JunyangShao]

I tried reproducing this on localhost and looks like it's only reproduced when it's read from http://localhost:6060/go.dev/src/cmd/compile/internal/ssa/README, i.e. the server. If I copy the same README content to another local file under website/_content the rendering error is gone.

Maybe @golang/tools-team

[qrasick]

I'd like to work on this issue.

After a little investigation, it seems that the cause is that .md files located under $GOROOT are also treated as templates.
I will attach a screenshot of the changes when I confirmed locally by actually adding template: false to the beginning of $GOROOT/src/cmd/compile/internal/ssa/README.md.

Based on the above, I am considering the following two approaches:

1. For .md files under $GOROOT where escaping is not working correctly, individually add template: false.
2. Do not treat .md files under $GOROOT as templates by default.

IMO, I believe that approach 1 could lead to a huge number of files needing modification, so approach 2 seems better.

In fact, it appears that there are no .md files under $GOROOT in Go 1.25 that explicitly specify the template parameter.

What do you think? @ansaba @golang/tools-team

[qrasick]

In the approach 2, it would be difficult to determine whether a Page belongs to contentFS or gorootFS. Therefore, the actual modification would likely be to default template: false for .md files whose request URL starts with /src/.
https://github.com/golang/website/blob/97294c2e6e681f4c539ab151abc6ce4ed0d0d28b/cmd/golangorg/server.go#L334-L336
cc: @rsc

[adonovan]

Ideally we would make the default that a file is not interpreted as a template, because this is a surprising thing. Would it be a lot of work to change the default and add the flag back only for those files where it makes a difference? Then you or we could audit those differences to see which are intentional and which are mistaken. Do you have any sense of how often templating was intended, and what it is used for? It would also be good to eliminate the difference between the localhost and production behavior as this is likely to cause more problems in future. Thanks.

[qrasick]

@adonovan

Would it be a lot of work to change the default and add the flag back only for those files where it makes a difference?

After actually investigating, it seems there are 136 .md files that would be affected if the default behavior for all .md files is changed.

Although the number is large, the modification required is simply to add "template: true", so it may be possible to handle it almost mechanically.

➜  website git:(master) ✗ grep -rl '{{' --include="*.md" . | xargs grep -L 'template: true' | wc -l
     136

Additionally, changing the default behavior for all .md files seems like it could be completed with a very minor modification.

In my personal opinion, I agree with changing the default behavior.

What do you think? Thanks.

[adonovan]

For the record the denominator is 482 .md files, so the 138 files using templating comprise about 29% of the total. Since it's clearly a minority, I agree it makes sense to flip the default, but let's add @dmitshur to the reviewers as he's the expert.

While you're here, it would be great if you could have a go at tracking down why the local/prod behaviors currently differ.

Thanks.