Skip to content

docs(site): highlight Cedar code blocks - #167

Merged
jonasz-lasut merged 4 commits into
mainfrom
docs/cedar-highlighting
Oct 11, 2026
Merged

jonasz-lasut merged 4 commits into
mainfrom
docs/cedar-highlighting

Conversation

@jonasz-lasut

Copy link
Copy Markdown
Owner

The documentation site's eleven ```cedar blocks rendered as plain text: eight worked examples in the Cedar policy reference, plus one each in HTTP egress, Signatures and Operator grant policy. mdBook 0.5.4 bundles highlight.js 10.1.1, which has no Cedar grammar.

Cedar has its own grammar, cedar-policy/highlightjs-cedar, the one docs.cedarpolicy.com uses. It is written for highlight.js 11 (match/scope modes, keyword arrays), though, and under 10.1.1 it throws TypeError: r.split is not a function. mdBook's main branch is still on 10.1.1. Replacing mdBook's highlight.js site-wide would break book.js, which calls the 10.x API: tabReplace, highlightBlock, and the stream merging that hidden Rust lines rely on, all removed in 11. Instead, docs/theme/cedar.js, loaded through additional-js, imports a private highlight.js 11 core and the grammar as ES modules and highlights only the Cedar blocks. mdBook's highlighter and every other block are untouched.

  • docs(site): vendor Cedar's highlight.js grammar: highlightjs-cedar v1.0.0 (dist/hljs-cedar.mjs, Apache-2.0, with its NOTICE) and highlight.js 11.11.1's ES core (es/core.min.js from @highlightjs/cdn-assets, BSD-3-Clause, 20 KB). Each file has a Vendored from header and its license beside it. The grammar comes from the GitHub release because the npm package highlightjs-cedar is published by an individual account, not the cedar-policy org.
  • docs(site): highlight Cedar code blocks: the loader, the book.toml entry and the AGENTS.md file map.
  • chore(renovate): track docs highlighting vendors: two regex managers over the headers, npm for the core and GitHub releases for the grammar. They are grouped as "docs Cedar highlighting" because the grammar targets one highlight.js major. As with the proto, a bump moves only the header; running make vendor-docs-highlight on the bump's branch fetches both files and their licenses at the versions the headers name. The files sit under docs/theme/ rather than a vendor/ directory because ignorePaths skips **/vendor/**.
  • docs: stop wrapped dashes rendering as bullets: in four places a wrapped line started with - or + , which CommonMark reads as the start of a bullet list. Grant policy, Sizing and two one-pagers showed a stray bullet mid-sentence. The lines are rewrapped.

Verified:

  • mdbook build (0.5.4) served locally and loaded in headless Chrome highlights all eleven blocks, on their own pages and in print.html, in the light and navy themes. The YAML and shell blocks beside them keep mdBook's highlighting.
  • lychee with the workflow's arguments reports no errors.
  • make vendor-docs-highlight reproduces the five vendored files byte for byte.
  • renovate-config-validator --strict (Renovate 44.149.3) accepts the config, and both managers' patterns match their files.

Two limits:

  • highlight.js 11 scopes in, like, has and is as operators. mdBook's 10.x theme CSS doesn't colour operators, so those words keep the text colour.
  • Opened from file://, the browser refuses the module imports, so the Cedar blocks stay plain text, as before. mdbook serve and GitHub Pages are unaffected.

Vendor cedar-policy/highlightjs-cedar v1.0.0 (dist/hljs-cedar.mjs) and
the highlight.js 11.11.1 ES core it is written for, each under a
"Vendored from" header and beside its license (and NOTICE for the
Apache-2.0 grammar). mdBook bundles highlight.js 10.1.1, which cannot
load the grammar, so the docs site needs its own core to run it.
The docs site's eleven ```cedar blocks rendered as plain text: mdBook's
highlight.js has no Cedar grammar. docs/theme/cedar.js, loaded through
book.toml's additional-js, imports the vendored highlight.js 11 core and
Cedar's own grammar and highlights only those blocks, leaving mdBook's
highlighter and every other block as they are.
Two regex managers read the "Vendored from" headers of the docs site's
highlight.js core (npm @highlightjs/cdn-assets) and Cedar grammar
(GitHub releases of cedar-policy/highlightjs-cedar), grouped into one
PR since the grammar targets one highlight.js major. As with the proto,
a bump moves the header only: `make vendor-docs-highlight` fetches both
files and their licenses at the versions the headers name, which
reproduces the vendored files byte for byte today.

The files live under docs/theme, not a vendor/ directory, because
ignorePaths skips **/vendor/**.
A line that starts with "- " or "+ " inside a paragraph opens a bullet
list in CommonMark, so four rewrapped sentences rendered with a stray
bullet in the middle (grant-policy, sizing and two one-pagers). Rewrap
them so the dash or plus stays mid-line.
@jonasz-lasut
jonasz-lasut merged commit 784fded into main Oct 11, 2026
5 checks passed
@jonasz-lasut
jonasz-lasut deleted the docs/cedar-highlighting branch October 11, 2026 09:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant