Repository navigation
docs(site): highlight Cedar code blocks - #167
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The documentation site's eleven
```cedarblocks 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/scopemodes, keyword arrays), though, and under 10.1.1 it throwsTypeError: 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 throughadditional-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.jsfrom@highlightjs/cdn-assets, BSD-3-Clause, 20 KB). Each file has aVendored fromheader and its license beside it. The grammar comes from the GitHub release because the npm packagehighlightjs-cedaris published by an individual account, not the cedar-policy org.docs(site): highlight Cedar code blocks: the loader, thebook.tomlentry 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; runningmake vendor-docs-highlighton the bump's branch fetches both files and their licenses at the versions the headers name. The files sit underdocs/theme/rather than avendor/directory becauseignorePathsskips**/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 inprint.html, in the light and navy themes. The YAML and shell blocks beside them keep mdBook's highlighting.lycheewith the workflow's arguments reports no errors.make vendor-docs-highlightreproduces 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:
in,like,hasandisas operators. mdBook's 10.x theme CSS doesn't colour operators, so those words keep the text colour.file://, the browser refuses the module imports, so the Cedar blocks stay plain text, as before.mdbook serveand GitHub Pages are unaffected.