From 388e4252344969863cd998a8b5af4b352a965a35 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Sat, 12 Sep 2026 01:48:51 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=92=84=E2=9C=A8=EF=BC=9Ahighlight=20code?= =?UTF-8?q?=20where=20it=20is=20built?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every fenced block on the site rendered as flat text. There was no highlighter registered with markdown-it and no token colors in the stylesheet, so a TypeScript example and a shell command read the same as prose in a box. Prism runs once, at build time. A page is static by the time anyone asks for it, and shipping a highlighter to mark it up again in the browser would be the same work done twice and later. Class-based, not inline styles, and that is not a preference. The SDK reference passes through the sanitizer before the layout embeds it, and its attribute allowlist has `class` but no `style`, so a highlighter that colors by attribute would have its work stripped from exactly those pages. Grammars are loaded by name rather than wholesale, and `ts`, `js`, `sh` and `shell` reach theirs through Prism's own aliases. `console` is the one the site uses that Prism does not know: a prompt with its output is `shell-session` there, so it is mapped. A flag with no grammar highlights nothing rather than failing, which is what `text` wants and what the generated corpus needs, since that carries flags from declarations this repository does not write. Flags are looked up in a map rather than on `Prism.languages` itself, because that object answers for its prototype as readily as for its grammars: a block flagged `constructor` finds `Object`'s and hands it to the tokenizer as though it were a grammar. The token colors are the site's palette shaded for contrast, not a theme borrowed from elsewhere: warm red for reserved words, teal for literals, muted ink for punctuation. Code sits on $secondary rather than on parchment, so each was measured against that. The lowest is 4.91:1 and the rest are above 6. `ts` joins the info string allowlist. The SDK settles on it as the one flag for TypeScript, and a page written here that borrows an example from there should not have to spell it the longer way to pass lint. Signed-off-by: Derek Lewis Assisted-by: Claude-Code:claude-opus-5 --- .remarkrc.mjs | 1 + _assets/styles/_code.scss | 71 +++++++++++++++++++++++++++++++++++++++ _assets/styles/main.scss | 1 + eleventy.config.mjs | 52 ++++++++++++++++++++++++++++ package.json | 2 ++ pnpm-lock.yaml | 23 +++++++++++++ project-terms.txt | 5 +-- 7 files changed, 153 insertions(+), 2 deletions(-) create mode 100644 _assets/styles/_code.scss diff --git a/.remarkrc.mjs b/.remarkrc.mjs index 4d9e19929..fdf11d3c7 100644 --- a/.remarkrc.mjs +++ b/.remarkrc.mjs @@ -52,6 +52,7 @@ const infoStrings = [ 'scheme', 'tex', 'text', + 'ts', 'typescript', 'yaml', ]; diff --git a/_assets/styles/_code.scss b/_assets/styles/_code.scss new file mode 100644 index 000000000..7851bde93 --- /dev/null +++ b/_assets/styles/_code.scss @@ -0,0 +1,71 @@ +@use 'sass:color'; + +// Token colors for the highlighting Prism does at build time. Code sits on +// $secondary rather than on the page, so every color here is chosen against +// that and not against parchment. The palette is the site's own, shaded for contrast rather than widened: +// warm red for the words a language reserves, teal for the values written +// literally, and the body's own muted ink for everything structural. Nothing +// here invents a hue the rest of the site does not use. + +$code-structural: color.mix($body-color, $secondary, 74%); +$code-comment: color.mix($body-color, $secondary, 72%); +$code-keyword: shade-color($quaternary, 22%); +$code-literal: shade-color($primary, 22%); +$code-callable: shade-color($primary, 48%); + +.doc-page .doc-prose pre code .token.comment, +.doc-page .doc-prose pre code .token.prolog, +.doc-page .doc-prose pre code .token.cdata { + font-style: italic; + color: $code-comment; +} + +.doc-page .doc-prose pre code .token.punctuation, +.doc-page .doc-prose pre code .token.operator, +.doc-page .doc-prose pre code .token.entity, +.doc-page .doc-prose pre code .token.url { + color: $code-structural; +} + +.doc-page .doc-prose pre code .token.keyword, +.doc-page .doc-prose pre code .token.atrule, +.doc-page .doc-prose pre code .token.rule, +.doc-page .doc-prose pre code .token.important, +.doc-page .doc-prose pre code .token.tag, +.doc-page .doc-prose pre code .token.selector { + color: $code-keyword; +} + +.doc-page .doc-prose pre code .token.string, +.doc-page .doc-prose pre code .token.char, +.doc-page .doc-prose pre code .token.number, +.doc-page .doc-prose pre code .token.boolean, +.doc-page .doc-prose pre code .token.constant, +.doc-page .doc-prose pre code .token.regex, +.doc-page .doc-prose pre code .token.attr-value { + color: $code-literal; +} + +.doc-page .doc-prose pre code .token.function, +.doc-page .doc-prose pre code .token.class-name, +.doc-page .doc-prose pre code .token.builtin, +.doc-page .doc-prose pre code .token.attr-name, +.doc-page .doc-prose pre code .token.property, +.doc-page .doc-prose pre code .token.symbol { + color: $code-callable; +} + +// A shell session prints its prompt and its output in the same block. The +// command is what a reader copies, so the rest recedes. +.doc-page .doc-prose pre code .token.output, +.doc-page .doc-prose pre code .token.shell-symbol { + color: $code-structural; +} + +.doc-page .doc-prose pre code .token.deleted { + color: shade-color($quaternary, 22%); +} + +.doc-page .doc-prose pre code .token.inserted { + color: shade-color($primary, 40%); +} diff --git a/_assets/styles/main.scss b/_assets/styles/main.scss index a11687425..18a377637 100644 --- a/_assets/styles/main.scss +++ b/_assets/styles/main.scss @@ -18,6 +18,7 @@ @import '../../node_modules/bootstrap/scss/nav'; @import '../../node_modules/bootstrap/scss/navbar'; @import 'about'; +@import 'code'; @import 'shell'; @import 'docs'; @import 'docs-page'; diff --git a/eleventy.config.mjs b/eleventy.config.mjs index a5824d9be..2fb266bff 100644 --- a/eleventy.config.mjs +++ b/eleventy.config.mjs @@ -12,10 +12,61 @@ import markdownItAnchor from 'markdown-it-anchor'; import markdownItFootnote from 'markdown-it-footnote'; import markdownItGitHubAlerts from 'markdown-it-github-alerts'; import postcss from 'postcss'; +import Prism from 'prismjs'; +import loadPrismLanguages from 'prismjs/components/index.js'; import { compileString } from 'sass'; import { optimize as optimizeSvg } from 'svgo'; import { minify as minifyJs } from 'terser'; +// Highlighting happens here rather than in the browser: a page is static by +// the time it is served, and shipping a highlighter to run over it again would +// be work done twice. Grammars are loaded once, at build time. +// +// Only what the site's own pages and the SDK's generated corpus actually use. +// Prism resolves `ts`, `js`, `sh` and `shell` through its own aliases, so this +// is a list of grammars rather than of the flags a fence may carry. +loadPrismLanguages([ + 'bash', + 'diff', + 'json', + 'markdown', + 'markup', + 'shell-session', + 'typescript', + 'yaml', +]); + +// Prism has no `console`; a prompt-and-output block is `shell-session` to it. +const PRISM_ALIASES = new Map([['console', 'shell-session']]); + +// Every grammar that got loaded, by name, aliases included. A map rather than +// `Prism.languages` itself, because looking a flag up on that object reaches +// its prototype as readily as its grammars: a block flagged `constructor` +// would find `Object`'s and be handed to the tokenizer as if it were one. The +// three helpers Prism keeps alongside the grammars are functions, and drop out +// on the same test. +const PRISM_GRAMMARS = new Map( + Object.entries(Prism.languages).filter( + ([, grammar]) => typeof grammar === 'object' + ) +); + +/** + * Marks up one fenced block, or gives markdown-it nothing and lets it escape + * the code itself. An unknown flag is not an error here: `text` is a fence + * with nothing to highlight, and the generated corpus carries flags from + * declarations this repository does not write. + * @param {string} code The block's contents. + * @param {string} flag Its info string. + * @returns {string} Highlighted HTML, or an empty string. + */ +const highlight = (code, flag) => { + const language = PRISM_ALIASES.get(flag) ?? flag; + const grammar = PRISM_GRAMMARS.get(language); + + return grammar === undefined ? '' : Prism.highlight(code, grammar, language); +}; + // skipcq: JS-0116 export default async function (eleventyConfig) { const isProduction = process.env.ELEVENTY_ENV === 'production'; @@ -24,6 +75,7 @@ export default async function (eleventyConfig) { eleventyConfig.addFilter('sanitizeSdkHtml', sanitizeSdkHtml); eleventyConfig.amendLibrary('md', (md) => { + md.set({ highlight }); md.use(markdownItAnchor); md.use(markdownItFootnote); // `> [!NOTE]` and the rest become a titled callout rather than a diff --git a/package.json b/package.json index 2c6fb970a..251bea13c 100644 --- a/package.json +++ b/package.json @@ -33,6 +33,7 @@ "@tsconfig/node-lts": "24.0.1", "@types/console-log-level": "1.4.5", "@types/node": "24.13.3", + "@types/prismjs": "1.26.6", "@types/sanitize-html": "2.16.1", "@yarnpkg/shell": "4.1.3", "autoprefixer": "10.5.4", @@ -58,6 +59,7 @@ "nps": "5.10.0", "postcss": "8.5.26", "prettier": "3.9.6", + "prismjs": "1.30.0", "remark": "15.0.1", "remark-cli": "12.0.1", "remark-frontmatter": "5.0.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0309b3434..73a36488d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -133,6 +133,9 @@ importers: '@types/node': specifier: 24.13.3 version: 24.13.3 + '@types/prismjs': + specifier: 1.26.6 + version: 1.26.6 '@types/sanitize-html': specifier: 2.16.1 version: 2.16.1 @@ -208,6 +211,9 @@ importers: prettier: specifier: 3.9.6 version: 3.9.6 + prismjs: + specifier: 1.30.0 + version: 1.30.0 remark: specifier: 15.0.1 version: 15.0.1(supports-color@10.2.2) @@ -1103,6 +1109,9 @@ packages: '@types/pluralize@0.0.29': resolution: {integrity: sha512-BYOID+l2Aco2nBik+iYS4SZX0Lf20KPILP5RGmM1IgzdwNdTs0eebiFriOPcej1sX9mLnSoiNte5zcFxssgpGA==} + '@types/prismjs@1.26.6': + resolution: {integrity: sha512-vqlvI7qlMvcCBbVe0AKAb4f97//Hy0EBTaiW8AalRnG/xAN5zOiWWyrNqNXeq8+KAuvRewjCVY1+IPxk4RdNYw==} + '@types/sanitize-html@2.16.1': resolution: {integrity: sha512-n9wjs8bCOTyN/ynwD8s/nTcTreIHB1vf31vhLMGqUPNHaweKC4/fAl4Dj+hUlCTKYgm4P3k83fmiFfzkZ6sgMA==} @@ -2195,6 +2204,10 @@ packages: resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==} engines: {node: '>=12'} + is-plain-object@5.0.0: + resolution: {integrity: sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==} + engines: {node: '>=0.10.0'} + is-plain-object@5.1.0: resolution: {integrity: sha512-bUi/yjmtKYcRVUtWRGr0UA6xEFh2I6zWUwMrUXB3s7bmYCaZ8a+0ZsTRkrawh/mzlSD1Y0Ph8bp/U+TvBpWDNw==} engines: {node: '>=0.10.0'} @@ -3049,6 +3062,10 @@ packages: engines: {node: '>=14'} hasBin: true + prismjs@1.30.0: + resolution: {integrity: sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==} + engines: {node: '>=6'} + proc-log@4.2.0: resolution: {integrity: sha512-g8+OnU/L2v+wyiVK+D5fA34J7EH8jZ8DDlvwhRCMxmMj7UCBvxiO1mGeN+36JXIKF4zevU4kRBd8lVgG9vLelA==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} @@ -4705,6 +4722,8 @@ snapshots: '@types/pluralize@0.0.29': {} + '@types/prismjs@1.26.6': {} + '@types/sanitize-html@2.16.1': dependencies: htmlparser2: 10.1.0 @@ -5769,6 +5788,8 @@ snapshots: is-plain-obj@4.1.0: {} + is-plain-object@5.0.0: {} + is-plain-object@5.1.0: {} is-promise@2.2.2: {} @@ -6886,6 +6907,8 @@ snapshots: prettier@3.9.6: {} + prismjs@1.30.0: {} + proc-log@4.2.0: {} promise-inflight@1.0.1: {} diff --git a/project-terms.txt b/project-terms.txt index b0be6aa65..8e41911b4 100644 --- a/project-terms.txt +++ b/project-terms.txt @@ -1,14 +1,15 @@ abled Aftertabs Anson +atrule autolinks backref bento bibtex biomejs blockified -Browserslist browserslist +Browserslist browserslistrc davidanson dbaeumer @@ -74,9 +75,9 @@ rowspan rubocop screencap sdcard +semgrep SEMGREP Semgrep -semgrep Servagility signingkey siteify