x/website,x/pkgsite: add support for syntax highlighting

[hyangah]

This is an umbrella issue for syntax highlighting support in various web properties owned and maintained by the Go project

• x/pkgsite: code block in comments x/pkgsite: add support for syntax highlighting of code blocks #40952
  example: https://pkg.go.dev/cloud.google.com/go/storage?tab=doc#hdr-Objects
  This can be tricky without a way to distinguish code blocks and pre-formatted non-code blocks.
• x/website: docs and tutorials x/website: Documentation supports code highlighting #55886
  examples:
  - https://go.dev/doc/tutorial/database-access
  - https://go.dev/doc/effective_go
  Source of these pages are html or a simplified md files. https://cs.opensource.google/go/x/website/+/master:_content/doc/
• x/playground, x/pkgsite: x/playground: support for syntax highlighting #34227 x/pkgsite: Syntax Highlight example blocks #52198 x/playground: add code highlighting #28539
  examples:
  - example code https://pkg.go.dev/io#example-Copy
• x/tour: tour partially supports syntax highlighting but that's unmaintained. Recent language updates aren't reflected.
  See x/playground: support for syntax highlighting #34227 (comment) for context.

[danawoodman]

II did a brief experiment to add syntax highlighting via https://github.com/yuin/goldmark-highlighting and it seems fairly easy to accomplish. Is this something the team is open to?

All that I think is required is a bit of configuration of goldmark-highlight and changing a given code block to have the language prefixed with language like you do in Github:

I think it would be pretty easy to progressively add this to pages in an incremental fashion until all properties have syntax highlighting. Is a PR welcome for this?

[griesemer]

I just want to note that syntax highlighting is (or can be) a controversial issue. I personally like it, but some people hate it. There are also UX issues for people who are color-blind and who may possibly experience syntax-highlighted code as harder to read (speak up if you have experience).

Can we have an unobtrusive and persistent way to enable/disable syntax highlighting so that people have a choice?

[rsc]

I agree. Please do not add syntax highlighting to pkgsite and the website. This was decided a long time ago and probably not worth revisiting. Thank you!

[ufukty]

Well I don't put a vote here in either side, just here to elaborate arguments.

I don't understand why authors choose to ignore community requests that completely aligns with industry wide practices by arguing the feature is only needed/prioritized by unexperienced users(?). Otherwise members of r/golang choosing alternative playgrounds* that support syntax highlighting to share examples perfectly indicates the direction of community vote. Also, I expect the lack of beginner friendly UI to create unwelcoming onboarding experience for the new developers, which might be a valid concern.

For accessibility related concerns, many of the modern operating systems provide "color filter" options each are optimized for different variation of color vision deficiencies. eg. iOS, Android, macOS, Windows. On top of that, adding a persistent toggle is completely fine and trivial.

For the implementation difficulty and frontend performance, the package site has the advantage of content being static. Thus, the to-HTML conversion can be performed server-side. There are plenty of packages for that such as alecthomas/chroma which is working fine in my documentation site project. Although it doesn't support LSP level type resolution. The variety of tokens is pretty limited, and the quality is incomparable to LSP.

*alternative playgrounds:

• goplay.tools (monaco based)
• goplay.space

[danawoodman]

@ufukty explained it clearly and eloquently

is the team open to a community poll on this?

i would assume the vast majority of end users of go would appreciate syntax highlighting to help them read and understand go code in the docs, REPL etc, but a poll could prove it either way

i know that go is famous for saying "no" to features and bloat (which we all deeply appreciate), but something that makes go more approachable to most users should be something worth seriously considering, especially if backed up by a community vote