docs(site): highlight Cedar code blocks

.github/renovate.json5

@@ -129,6 +129,34 @@
       datasourceTemplate: 'crate',
       versioningTemplate: 'semver',
     },
+    {
+      // The documentation site's Cedar highlighting (docs/theme/cedar.js):
+      // the highlight.js 11 core and Cedar's own grammar, each vendored under
+      // docs/theme (not under a vendor/ directory: ignorePaths skips those)
+      // as the upstream file beneath a one-line header naming the release.
+      // Same tripwire as the proto: a bump PR moves the header and does NOT
+      // re-download the file, so run `make vendor-docs-highlight` on its
+      // branch, which fetches both at the versions their headers name, and
+      // check the Cedar pages render.
+      customType: 'regex',
+      description: 'highlight.js release the docs site runs the Cedar grammar on',
+      managerFilePatterns: ['/^docs/theme/highlightjs/core\\.min\\.js$/'],
+      matchStrings: [
+        'Vendored from @highlightjs/cdn-assets (?<currentValue>\\d+\\.\\d+\\.\\d+) ',
+      ],
+      depNameTemplate: '@highlightjs/cdn-assets',
+      datasourceTemplate: 'npm',
+    },
+    {
+      customType: 'regex',
+      description: 'cedar-policy/highlightjs-cedar release the docs site highlights Cedar with',
+      managerFilePatterns: ['/^docs/theme/highlightjs-cedar/hljs-cedar\\.esm\\.js$/'],
+      matchStrings: [
+        'Vendored from cedar-policy/highlightjs-cedar (?<currentValue>v\\d+\\.\\d+\\.\\d+) ',
+      ],
+      depNameTemplate: 'cedar-policy/highlightjs-cedar',
+      datasourceTemplate: 'github-releases',
+    },
   ],
   // Rules are evaluated in order; later rules win.
   packageRules: [
@@ -216,6 +244,13 @@
       matchPackageNames: ['wasmtime-wasi-http'],
       enabled: true,
     },
+    // The docs site's Cedar grammar is written for one highlight.js major,
+    // so a bump of either is judged with the other in one PR.
+    {
+      matchManagers: ['custom.regex'],
+      matchPackageNames: ['@highlightjs/cdn-assets', 'cedar-policy/highlightjs-cedar'],
+      groupName: 'docs Cedar highlighting',
+    },
 
     // The monthly examples refresh. The examples are illustrative and never
     // shipped (the image holds only the runtime binary), so one batch a

AGENTS.md

@@ -424,8 +424,11 @@ docs/abi-v2.md              the host/guest contract: the component world every s
 book.toml, docs/SUMMARY.md  the documentation site (mdBook over docs/; "Documentation site" below):
                             the manual's pages under docs/guests, docs/operators, docs/contract and
                             docs/project, the one-pagers and docs/abi-v2.md listed beside them,
-                            docs/theme/wasm.css the accent stylesheet; .github/workflows/docs.yml
-                            builds, link-checks and deploys it
+                            docs/theme/wasm.css the accent stylesheet, docs/theme/cedar.js the
+                            Cedar code-block highlighting (Cedar's own highlightjs-cedar grammar on a
+                            private highlight.js 11 core, both vendored under docs/theme/ with their
+                            licenses: mdBook's bundled 10.1.1 cannot load it);
+                            .github/workflows/docs.yml builds, link-checks and deploys it
 ```
 
 ## Key Concepts
@@ -556,7 +559,7 @@ make -C examples/dashboard-bundle lint              # dotnet format (in the .NET
 
 ### Documentation site
 
-The user manual is an mdBook under `docs/`: `book.toml` at the repository root (`src = "docs"`), `docs/SUMMARY.md` the table of contents, the pages under `docs/guests/`, `docs/operators/`, `docs/contract/` and `docs/project/`, with `docs/abi-v2.md` and the one-pagers listed from where they are (the code and the conformance goldens name them by path, so they never move). It is published at <https://jonasz-lasut.github.io/function-wasm/> by `.github/workflows/docs.yml`: a pull request touching `docs/**`, `book.toml`, `README.md` or `SECURITY.md` builds it and link-checks the rendered site offline (lychee, every internal link and anchor), a push to `main` deploys it to GitHub Pages. Build it locally with `cargo install mdbook --locked --version 0.5.4` and `mdbook build` (output under `book/`, ignored); the workflow pins the same version by checksum. User-facing behaviour is documented in `docs/`: a new capability, flag, field or refusal lands on its page there, and the README is the landing page only - the pitch, the install snippet, a quick start and links into the site - so it needs no update when a feature lands.
+The user manual is an mdBook under `docs/`: `book.toml` at the repository root (`src = "docs"`), `docs/SUMMARY.md` the table of contents, the pages under `docs/guests/`, `docs/operators/`, `docs/contract/` and `docs/project/`, with `docs/abi-v2.md` and the one-pagers listed from where they are (the code and the conformance goldens name them by path, so they never move). It is published at <https://jonasz-lasut.github.io/function-wasm/> by `.github/workflows/docs.yml`: a pull request touching `docs/**`, `book.toml`, `README.md` or `SECURITY.md` builds it and link-checks the rendered site offline (lychee, every internal link and anchor), a push to `main` deploys it to GitHub Pages. Build it locally with `cargo install mdbook --locked --version 0.5.4` and `mdbook build` (output under `book/`, ignored); the workflow pins the same version by checksum. The ```` ```cedar ```` blocks are highlighted by `docs/theme/cedar.js` with Cedar's own grammar (`cedar-policy/highlightjs-cedar`) on a private highlight.js 11 core, mdBook's bundled highlight.js 10.1.1 being unable to load it; both are vendored under `docs/theme/` beneath a `Vendored from` header Renovate tracks (grouped as "docs Cedar highlighting"), and a bump PR is the signal to run `make vendor-docs-highlight` on its branch, which fetches them at the versions the headers name. User-facing behaviour is documented in `docs/`: a new capability, flag, field or refusal lands on its page there, and the README is the landing page only - the pitch, the install snippet, a quick start and links into the site - so it needs no update when a feature lands.
 
 ## Common Development Tasks
 

Makefile

@@ -22,7 +22,7 @@
 # change to a world, a re-vendoring of the WASI WIT, or a wit-bindgen bump
 # (the generated files' header names the version; e2e.yml's drift checks
 # install the same one).
-.PHONY: vendor-proto vendor-proto-fetch vendor-proto-codecs vendor-proto-goldens gen-bindings tools tools-clean
+.PHONY: vendor-proto vendor-proto-fetch vendor-proto-codecs vendor-proto-goldens vendor-docs-highlight gen-bindings tools tools-clean
 # The steps rewrite one another's inputs; never run them side by side.
 .NOTPARALLEL:
 
@@ -110,6 +110,38 @@ vendor-proto-codecs: tools ## Regenerate every checked-in guest codec with the p
 vendor-proto-goldens: ## Refresh the guestfn scaffold goldens from the templates
 	UPDATE_GOLDENS=1 cargo test -p guestfn
 
+# The documentation site's Cedar highlighting (docs/theme/cedar.js) runs
+# cedar-policy/highlightjs-cedar's grammar on a private highlight.js 11 core,
+# each vendored under docs/theme as the upstream file beneath a one-line
+# header naming the release, which Renovate's version-header rules read. A
+# bump PR moves a header only, so it is the signal to run
+# `make vendor-docs-highlight` on the PR's branch: both files and their
+# licenses are fetched again at the versions the headers name.
+HLJS_CORE := docs/theme/highlightjs/core.min.js
+HLJS_CEDAR := docs/theme/highlightjs-cedar/hljs-cedar.esm.js
+HLJS_VERSION := $(shell sed -n '1s|^// Vendored from @highlightjs/cdn-assets \([0-9.]*\) .*|\1|p' $(HLJS_CORE))
+HLJS_CEDAR_VERSION := $(shell sed -n '1s|^// Vendored from cedar-policy/highlightjs-cedar \(v[0-9.]*\) .*|\1|p' $(HLJS_CEDAR))
+HLJS_CEDAR_URL := https://raw.githubusercontent.com/cedar-policy/highlightjs-cedar/$(HLJS_CEDAR_VERSION)
+
+vendor-docs-highlight: ## Re-vendor the docs site's highlight.js core and Cedar grammar, with their licenses, at the versions their headers name
+	@expr '$(HLJS_VERSION)' : '[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*$$' >/dev/null || \
+		{ echo "$(HLJS_CORE): line 1 names no @highlightjs/cdn-assets release (X.Y.Z)" >&2; exit 1; }
+	@expr '$(HLJS_CEDAR_VERSION)' : 'v[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*$$' >/dev/null || \
+		{ echo "$(HLJS_CEDAR): line 1 names no cedar-policy/highlightjs-cedar release (vX.Y.Z)" >&2; exit 1; }
+	@set -e; \
+	tarball=$$(mktemp); trap 'rm -f "$$tarball"' EXIT; \
+	echo "fetching @highlightjs/cdn-assets $(HLJS_VERSION)"; \
+	curl -fsSL -o "$$tarball" 'https://registry.npmjs.org/@highlightjs/cdn-assets/-/cdn-assets-$(HLJS_VERSION).tgz'; \
+	{ head -n 1 $(HLJS_CORE); tar -xzOf "$$tarball" package/es/core.min.js; } > $(HLJS_CORE).tmp; \
+	mv $(HLJS_CORE).tmp $(HLJS_CORE); \
+	tar -xzOf "$$tarball" package/LICENSE > $(dir $(HLJS_CORE))LICENSE; \
+	echo "fetching cedar-policy/highlightjs-cedar $(HLJS_CEDAR_VERSION)"; \
+	{ head -n 1 $(HLJS_CEDAR); curl -fsSL '$(HLJS_CEDAR_URL)/dist/hljs-cedar.mjs'; } > $(HLJS_CEDAR).tmp; \
+	mv $(HLJS_CEDAR).tmp $(HLJS_CEDAR); \
+	curl -fsSL -o $(dir $(HLJS_CEDAR))LICENSE '$(HLJS_CEDAR_URL)/LICENSE'; \
+	curl -fsSL -o $(dir $(HLJS_CEDAR))NOTICE '$(HLJS_CEDAR_URL)/NOTICE'
+	@echo "vendored highlight.js $(HLJS_VERSION) and highlightjs-cedar $(HLJS_CEDAR_VERSION): review git diff, then check the Cedar pages under mdbook serve"
+
 # The bindings are mirrored whole: wit-bindgen writes exactly the three files
 # the c and zig templates carry (function.c, function.h,
 # function_component_type.o), and for go a wit_bindings.go and an empty.s

book.toml

@@ -23,6 +23,9 @@ edit-url-template = "https://github.com/jonasz-lasut/function-wasm/edit/main/{pa
 default-theme = "light"
 preferred-dark-theme = "navy"
 additional-css = ["docs/theme/wasm.css"]
+# mdBook's highlight.js has no Cedar grammar; docs/theme/cedar.js highlights
+# the ```cedar blocks with Cedar's own (vendored beside it in docs/theme/).
+additional-js = ["docs/theme/cedar.js"]
 
 [output.html.search]
 limit-results = 20

docs/one-pager-admission-tooling.md

@@ -82,8 +82,8 @@ composition.yaml: Composition/hello pipeline[0] greeter: OK (oci ghcr.io/example
 composition.yaml: Composition/hello pipeline[1] labeler: refused: module oci ghcr.io/example/labeler@sha256:9d1c… requires egress GET to host "evil.example.com" (requires.egress.http[0]), which the operator policy (--sandbox-policy-file) does not permit
 ```
 
-`--resolve` goes one step further: `Resolve` + `Verify` (with `--cosign-key`)
-+ fetch through the same resolver, then `engine.Inspect` — the module
+`--resolve` goes one step further: `Resolve` + `Verify` (with
+`--cosign-key`) + fetch through the same resolver, then `engine.Inspect` — the module
 compiled with the runtime's own wasmtime engine, its size, ABI verdict and
 host imports reported (the module manifest of
 `docs/one-pager-module-manifest.md`, once it exists, is checked here too).

docs/one-pager-sandbox.md

@@ -122,8 +122,8 @@ directory into a module: what a module can read is its request, what it can
 write is its private `/tmp`. `internal/authz.LoadOperatorPolicy`,
 `internal/egress.New` and `internal/sandbox.NewCeiling` check the policy once at
 startup - a `--sandbox-policy-file` that does not parse (a malformed ip-rule
-included), or an unwritable `$TMPDIR` when the policy can grant a private `/tmp`
-- and refuse to start rather than fail every request that would hit the mistake.
+included), or an unwritable `$TMPDIR` when the policy can grant a private
+`/tmp` - and refuse to start rather than fail every request that would hit the mistake.
 Between load and run `admission.AdmitRequires` decides the module's ask,
 giving the run its sandbox or a fatal result: with no policy, `module …
 requires a private /tmp (requires.filesystem.privateTmp), but the runtime has

docs/operators/grant-policy.md

@@ -28,9 +28,9 @@ is presently always empty). The actions are `usePrivateTmp`, `setEnv`,
 `Credential::"<name>"`, for egress the host or pattern within a
 boundary-correct `HostPattern` hierarchy, and the context carries the method
 and path. A separate, caller-independent action `requireSignature` (over the
-`Repository` hierarchy) decides which repositories must carry a cosign signature
-- see [signing](signatures.md). A policy that lets only `team-a` use a
-private `/tmp` and lets any namespace reach `*.example.com`:
+`Repository` hierarchy) decides which repositories must carry a cosign
+signature - see [signing](signatures.md). A policy that lets only `team-a`
+use a private `/tmp` and lets any namespace reach `*.example.com`:
 
 ```cedar
 permit (principal, action == Action::"usePrivateTmp", resource)

docs/operators/sizing.md

@@ -18,8 +18,8 @@ scaffold is now ~240 KB):
 | on disk per module version | ~230 MB (module + artifact) | ~60 MB | 5 MB | 0.9 MB |
 | load from a warm volume | 6–8 ms | 2 ms | 0.2 ms | 0.05 ms |
 
-Rules of thumb: memory ≈ resident modules + `--max-concurrent-compiles` × 1 GB
-+ concurrent runs × 16 MB (`--max-concurrent-runs` caps that last term when
+Rules of thumb: memory ≈ resident modules + `--max-concurrent-compiles` ×
+1 GB + concurrent runs × 16 MB (`--max-concurrent-runs` caps that last term when
 the caller's concurrency is not the number you want to size for); a cold
 start compiles every module once, so ten Go modules on two cores take about
 two minutes and a warm volume under `/tmp/function-wasm-cache` turns that

docs/theme/cedar.js

@@ -0,0 +1,30 @@
+/* Cedar syntax highlighting for the documentation site, by Cedar's own
+   grammar (cedar-policy/highlightjs-cedar, vendored beside this file).
+   The grammar is written for highlight.js 11 and mdBook bundles 10.1.1,
+   which cannot load it, so a private highlight.js 11 core highlights the
+   ```cedar blocks and nothing else: mdBook's highlighter and every other
+   block stay as they are. book.js has already run and left the Cedar
+   blocks as plain text, their language being unknown to it. Loaded through
+   book.toml's additional-js; the vendored modules are the copies mdBook
+   makes of everything under docs/, found from mdBook's path_to_root. */
+
+(function () {
+    "use strict";
+
+    const blocks = document.querySelectorAll("code.language-cedar");
+    if (blocks.length === 0) {
+        return;
+    }
+
+    const theme = new URL(path_to_root + "theme/", document.baseURI);
+    Promise.all([
+        import(new URL("highlightjs/core.min.js", theme)),
+        import(new URL("highlightjs-cedar/hljs-cedar.esm.js", theme)),
+    ]).then(function ([core, cedar]) {
+        const hljs11 = core.default;
+        hljs11.registerLanguage("cedar", cedar.hljsCedar);
+        blocks.forEach(function (block) {
+            hljs11.highlightElement(block);
+        });
+    });
+})();