Syntax highlight at build time

[toastal]

The use of highlight.js has some issues:

1. a user with JavaScript disabled by default for security reasons, will not get syntax highlighting
2. a user with must trust a third-party CDN for delivery
   a. with browser sandboxing, there is no performance benefit from using a CDN in this way
   b. the CDN will leak private user data such as IPs to an entity that may not act in good faith with that data
   c. subresource-integrity check is also missing so this code could be insecure and changed by the CDN at will because it's not within Gleam's control
   d. technically since these URLs lack the protocol, they could be served over the insecure HTTP vs. HTTPS+TLS
3. a user must execute the same syntax highlight parsing code as all other users
   a. wasteful to CPU + battery
   b. wasteful on the network (and user data plans)
   c. introducing a rendering and paint delay

My suggestion is to render syntax highlighting at build time and include the syntax highlighting CSS into the base style sheet. This would mean the syntax highlighting step would be executed once and it would be static. Built static, this eliminates the need for JavaScript for the basic documentation, does not require consenting to third-party CDN and security risks involved with it, saves people's CPUs+batteries+data plans, and would increase render performance.

[lpil]

Hello!

Sounds good. Do you have any ideas for how we would do this?

[toastal]

A quick phase 1 could be hosting the highlight.js files on the project's domain so that it's first-party code and can be trusted to a greater degree.

A phase 2... well, peeking at the source, it appears mdbook is used and it doesn't do this rendering server side--meaning all downstream projects have this issue (which I didn't realize when I opened this). Route 1 would be getting mdbook to get this feature, or route 2 use a another tool to parse and add syntax highlighting (anecdote: to fix rendering on SourceHut, I used a script with OCaml + Lambda Soup to pipe to a highlighter and post-process the output).

[lpil]

We intend to stop using mdbook in future, just not something we've got around to yet.

[Enderchief]

For syntax highlighting at build time, the syntect library (written in Rust) could work. Deno Doc uses it for documentation. (See this package for an example: https://deno.land/x/[email protected]/application.ts)

[lpil]

Another option would be to teach the compiler how to print with colours, seeing as it already knows the Gleam grammar. Avoid a large-ish dep.