[Bug]: Code blocks in additionalLanguages languages render without syntax highlighting #1293

Page or section

Site-wide: every code block in a language listed in prism.additionalLanguages (docusaurus.config.ts). That's bash, json, powershell, docker, promql, and, since #1291, hcl.

What's wrong?

These blocks render with only token plain spans, so they show no syntax highlighting. It happens on production and on a local production build. For example, every bash and powershell block on https://docs.stacklok.com/toolhive/guides-cli/api-server renders plain. Languages that ship with prism-react-renderer, such as yaml, still highlight.

At runtime, window.Prism is { manual: true } and has no languages property. docusaurus-theme-redoc, which comes in through redocusaurus, sets it in a client module (src/global.ts):

if (ExecutionEnvironment.canUseDOM) {
  window.Prism = window.Prism || {};
  window.Prism.manual = true;
}

The root cause isn't confirmed yet. Docusaurus's prism-include-languages swaps in its own Prism instance while it loads the extra grammars, so that client module alone shouldn't break them. One suspect is Redoc's bundled prismjs: if it loads the same prismjs/components/* modules first, webpack's module cache would register them on Redoc's Prism instance, and they'd never reach Docusaurus's.

Suggested fix

• Confirm the cause. A quick test is a build with redocusaurus temporarily removed from presets, checking whether bash blocks highlight.
• If Redoc is the cause, options include:
  • swizzling prism-include-languages so it registers grammars on prism-react-renderer's Prism explicitly
  • limiting Redoc's client module to the API reference pages
  • taking it upstream to redocusaurus
• Add a visual regression or unit check so highlighting doesn't silently regress again.

Additional context

Found while adding hcl for a Terraform example in #1291. Related: #1292.

Fully or partially written by an AI agent.