From 89cb2b379f9da776597cf0991f011f8d4f269255 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 2 Nov 2026 14:59:42 +0000 Subject: [PATCH 1/3] feat: add a highlighter option for content code blocks comarkDocs.highlighter points at a module whose default export is the comark plugin that highlights code blocks, so a site can use shiki and its themes instead of the layer's rangi and Geist theme without patching the layer. The runtime parser imports it through #comark-docs/highlighter, the build-time snapshot loads the same file, and a hash of it joins the content cache namespace. Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30 --- modules/config/index.ts | 20 +++++++++-- modules/snapshot/index.ts | 12 +++++-- .../1.getting-started/3.configuration.md | 24 +++++++++++++ server/utils/cache.ts | 10 ++++-- server/utils/content.ts | 12 ++++--- test/highlighter.test.ts | 35 +++++++++++++++++++ utils/factory.ts | 23 ++++++------ utils/highlighter.ts | 5 +++ vitest.config.ts | 3 ++ 9 files changed, 124 insertions(+), 20 deletions(-) create mode 100644 test/highlighter.test.ts create mode 100644 utils/highlighter.ts diff --git a/modules/config/index.ts b/modules/config/index.ts index da1c679..41cc61e 100644 --- a/modules/config/index.ts +++ b/modules/config/index.ts @@ -1,5 +1,6 @@ -import { existsSync, readdirSync } from 'node:fs' -import { addServerPlugin, createResolver, defineNuxtModule, useLogger } from '@nuxt/kit' +import { createHash } from 'node:crypto' +import { existsSync, readdirSync, readFileSync } from 'node:fs' +import { addServerPlugin, createResolver, defineNuxtModule, resolvePath, useLogger } from '@nuxt/kit' import { defu } from 'defu' import type { ModuleOptions as AgentDiscoveryOptions } from 'nuxt-agent-discovery' import { getGitBranch, getGitEnv, getGitRoot, getLocalGitInfo } from '../../utils/git' @@ -25,6 +26,11 @@ export interface ComarkDocsOptions { /** GitHub repos (`owner/name`) `/api/code-explorer` may read. Defaults to the content repo only. */ allowRepos?: string[] } + /** + * Module whose default export is the comark plugin that highlights code blocks in content, such as + * `shiki({ themes })`, resolved from the app root. Defaults to rangi with the layer's Geist theme. + */ + highlighter?: string /** @deprecated Use `agentDiscovery.skills` instead. */ skills?: { dir?: string @@ -217,6 +223,16 @@ export default defineNuxtModule({ const { resolve } = createResolver(import.meta.url) addServerPlugin(resolve('./runtime/server/plugins/llms')) + // The runtime parser imports the highlighter through this alias, and the snapshot module loads the same file. + const highlighter = options.highlighter + ? await resolvePath(options.highlighter, { cwd: rootDir }) + : resolve('../../utils/highlighter.ts') + nuxt.options.alias['#comark-docs/highlighter'] = highlighter + // A site's highlighter changes the parsed output, so it gets its own content cache namespace. + nuxt.options.runtimeConfig.docs.highlighterVersion = options.highlighter + ? createHash('sha256').update(readFileSync(highlighter)).digest('hex').slice(0, 8) + : '' + // ISR rules here (not `$production`) so they merge cleanly across npm layers; content sections need a redeploy. if (!nuxt.options.dev && options.isr !== false) { const isr = options.isr! diff --git a/modules/snapshot/index.ts b/modules/snapshot/index.ts index f504ee0..9f13448 100644 --- a/modules/snapshot/index.ts +++ b/modules/snapshot/index.ts @@ -1,13 +1,15 @@ import { mkdir, stat } from 'node:fs/promises' -import { defineNuxtModule, useLogger } from '@nuxt/kit' +import { createResolver, defineNuxtModule, useLogger } from '@nuxt/kit' import { DEFAULT_CONTENT_NAME } from 'comark-content' import { writeSnapshots } from 'comark-content/build' import fs from 'comark-content/sources/fs' import { join } from 'pathe' import { createBuildContentInstance } from '../../utils/factory' +import defaultHighlighter from '../../utils/highlighter' import { resolveSnapshotSha } from './utils' const logger = useLogger('comark-docs') +const defaultHighlighterPath = createResolver(import.meta.url).resolve('../../utils/highlighter.ts') /** Where the snapshot lives in the build, and the server-asset namespace it is read back through. */ const ASSET_BASE = 'comark-content' @@ -56,7 +58,13 @@ export default defineNuxtModule({ // `withRef` stamps the artifact with the commit. // At runtime, even with a different commit, we can reuse unchanged bodies. - const content = createBuildContentInstance({ source: fs(contentPath) }).withRef(sha) + // The highlighter the runtime parser imports through `#comark-docs/highlighter`. The layer's default is + // imported statically, since Node won't strip types from a `.ts` file in node_modules. + const highlighterPath = nuxt.options.alias['#comark-docs/highlighter']! + const highlighter = highlighterPath === defaultHighlighterPath + ? defaultHighlighter + : (await import(highlighterPath)).default + const content = createBuildContentInstance({ source: fs(contentPath) }, highlighter).withRef(sha) try { const writeStart = performance.now() diff --git a/playground/content/1.getting-started/3.configuration.md b/playground/content/1.getting-started/3.configuration.md index f0043e5..b96c94d 100644 --- a/playground/content/1.getting-started/3.configuration.md +++ b/playground/content/1.getting-started/3.configuration.md @@ -45,11 +45,35 @@ export default defineNuxtConfig({ | `isr` | `300` | ISR expiration in seconds for the generated route rules. Set to `false` to disable them entirely. | | `contentDir` | inferred | Content directory **relative to the repository root** (an app in `docs/` becomes `docs/content`). Inferred from the local git checkout. | | `codeExplorer.allowRepos` | `[]` | Extra `owner/repo` entries the [CodeExplorer component](/writing/components#codeexplorer) may fetch from. The content repository is always allowed. | +| `highlighter` | rangi, Geist theme | Module whose default export is the comark plugin that highlights code blocks, resolved from the app root. See [Code highlighting](#code-highlighting). | ::warning A build that can't see `.git` (a shallow Docker build, an exported tarball) can't infer `contentDir` and assumes the app is the repository root. If your app lives in a subdirectory, set `comarkDocs.contentDir` (or `NUXT_DOCS_CONTENT_DIR`) explicitly — the build warns when it has to guess. :: +### Code highlighting + +Content code blocks are highlighted with [rangi](https://comark.dev/plugins/built-in/rangi) and the layer's Geist theme. To use another highlighter, export it as a comark plugin from a file and point `highlighter` at it, such as comark's [Shiki plugin](https://comark.dev/plugins/built-in/shiki) with the Vitesse themes: + +```ts [highlighter.ts] +import shiki from 'comark/plugins/shiki' +import vitesseDark from '@shikijs/themes/vitesse-dark' +import vitesseLight from '@shikijs/themes/vitesse-light' + +export default shiki({ registerDefaultThemes: false, themes: { light: vitesseLight, dark: vitesseDark } }) +``` + +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + extends: ['comark-docs'], + comarkDocs: { + highlighter: './highlighter.ts', + }, +}) +``` + +Install what the file imports in your app, here `comark`, `shiki` and `@shikijs/themes`. Both the build-time snapshot and the runtime parser use it, and the parsed pages are cached under a key that includes a hash of the file, so changing it never serves pages highlighted by the previous one. + ### agentDiscovery options [Markdown for agents](/concepts/architecture#markdown-for-agents) is [nuxt-agent-discovery](https://github.com/benjamincanac/nuxt-agent-discovery), configured under `agentDiscovery`. The layer points it at the content instance, keeps versioned previews out of negotiation and seeds the MCP server card. Everything else is the module's defaults, and the option you are most likely to touch is the [Agent Skills](https://agentskills.io) directory: diff --git a/server/utils/cache.ts b/server/utils/cache.ts index 72455cf..ee5a3cb 100644 --- a/server/utils/cache.ts +++ b/server/utils/cache.ts @@ -19,6 +19,12 @@ function runtimeCacheDriver(base: string, ttl?: number): Driver { */ export const CONTENT_PARSER_VERSION = 'v6' +/** The parser version, plus a hash of the site's `comarkDocs.highlighter` when it sets one. */ +function parserVersion(): string { + const { highlighterVersion } = useRuntimeConfig().docs + return highlighterVersion ? `${CONTENT_PARSER_VERSION}-${highlighterVersion}` : CONTENT_PARSER_VERSION +} + /** * A ref pinned via `withRef()` is treated as immutable, so it can be cached for a long time. */ @@ -29,7 +35,7 @@ const IMMUTABLE_TTL = 60 * 60 * 24 * Base namespace is per parser version and keys are per-sha. */ export function contentCacheDriver(): Driver { - return runtimeCacheDriver(`content:${CONTENT_PARSER_VERSION}`, IMMUTABLE_TTL) + return runtimeCacheDriver(`content:${parserVersion()}`, IMMUTABLE_TTL) } /** @@ -50,7 +56,7 @@ export function refCacheDriver(ttl: number): Driver { * Namespace is per-sha and keys start with `gh:`. */ export function shaCacheStorage(sha: string): Storage { - return createStorage({ driver: runtimeCacheDriver(`content:${CONTENT_PARSER_VERSION}:${sha}`, IMMUTABLE_TTL) }) + return createStorage({ driver: runtimeCacheDriver(`content:${parserVersion()}:${sha}`, IMMUTABLE_TTL) }) } /** Short TTL. `branch` is mutable. */ diff --git a/server/utils/content.ts b/server/utils/content.ts index b201804..8791039 100644 --- a/server/utils/content.ts +++ b/server/utils/content.ts @@ -3,6 +3,7 @@ import fs from 'comark-content/sources/fs' import forge from 'comark-content/sources/forge' import { withSnapshot } from 'comark-content/sources/snapshot' import { createRuntimeContentInstance } from '../../utils/factory.ts' +import highlighter from '#comark-docs/highlighter' /** * The instance serving requests in this layer. @@ -22,10 +23,13 @@ function getBaseContent(): DocsContent { } function createBaseContent() { - return createRuntimeContentInstance({ - source: contentSource(), - cache: { driver: contentCacheDriver() }, - }) + return createRuntimeContentInstance( + { + source: contentSource(), + cache: { driver: contentCacheDriver() }, + }, + highlighter, + ) } /** diff --git a/test/highlighter.test.ts b/test/highlighter.test.ts new file mode 100644 index 0000000..2053bb4 --- /dev/null +++ b/test/highlighter.test.ts @@ -0,0 +1,35 @@ +import { mkdtemp, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { expect, it } from 'vitest' +import type { ComarkPlugin } from 'comark' +import fsSource from 'comark-content/sources/fs' +import { createBuildContentInstance } from '../utils/factory' +import defaultHighlighter from '../utils/highlighter' + +async function parse(highlighter: ComarkPlugin) { + const dir = await mkdtemp(join(tmpdir(), 'comark-docs-highlighter-')) + await writeFile(join(dir, 'index.md'), '```ts\nconst answer = 42\n```\n') + return JSON.stringify(await createBuildContentInstance({ source: fsSource(dir) }, highlighter).get('/')) +} + +// `comarkDocs.highlighter` replaces rangi: the plugin a site passes runs, and the default one doesn't. +it('highlights code blocks with the highlighter it is given', async () => { + const marker: ComarkPlugin = { + name: 'test-highlighter', + post({ tree }) { + const mark = (node: unknown) => { + if (!Array.isArray(node)) return + if (node[0] === 'pre') node[1] = { ...node[1], highlightedBy: 'test' } + node.slice(2).forEach(mark) + } + tree.nodes.forEach(mark) + }, + } + const custom = await parse(marker) + expect(custom).toContain('"highlightedBy":"test"') + expect(custom).not.toContain('#c41562') + + // Geist's keyword color, so the default is rangi with the layer's theme. + expect(await parse(defaultHighlighter)).toContain('#c41562') +}) diff --git a/utils/factory.ts b/utils/factory.ts index 120ac52..472ae01 100644 --- a/utils/factory.ts +++ b/utils/factory.ts @@ -1,23 +1,23 @@ import type { Tracer } from '@opentelemetry/api' +import type { ComarkPlugin } from 'comark' import { type ContentOptions, comarkContent } from 'comark-content' import markdown from 'comark-content/plugins/markdown' import yaml from 'comark-content/plugins/yaml' import tracingOtel from 'comark-content/plugins/tracing/otel' -import rangi from 'comark/plugins/rangi' import security from 'comark/plugins/security' import emoji from 'comark/plugins/emoji' import toc from 'comark/plugins/toc' import mermaid from 'comark/plugins/mermaid' -import { geistTheme } from './geist.ts' import { contentTracer } from '../server/utils/tracer.ts' /** Frontmatter kept in the manifest, so `list()` and `navigation()` render without reading bodies. */ const LISTING_FIELDS = ['title', 'description', 'navigation', 'icon', 'layout'] // Bump CONTENT_PARSER_VERSION in `server/utils/cache.ts` when these plugins or their options change cached output. -const comarkPlugins = [ +// The highlighter is the site's choice (`comarkDocs.highlighter`), so it is passed in. +const comarkPlugins = (highlighter: ComarkPlugin) => [ mermaid({ theme: 'zinc-light', themeDark: 'zinc-dark' }), - rangi({ theme: geistTheme }), + highlighter, toc({ depth: 3 }), emoji(), security({ @@ -31,12 +31,12 @@ const comarkPlugins = [ * - The build-time snapshot * - The runtime instance */ -function create(options: Pick, tracer?: Tracer) { +function create(options: Pick, highlighter: ComarkPlugin, tracer?: Tracer) { return comarkContent({ source: options.source, plugins: [ markdown({ - comark: { plugins: comarkPlugins }, + comark: { plugins: comarkPlugins(highlighter) }, listingFields: LISTING_FIELDS, }), yaml({ listingFields: LISTING_FIELDS }), @@ -48,13 +48,16 @@ function create(options: Pick, } /** An instance serving requests: traced, and cached per content SHA. */ -export function createRuntimeContentInstance(options: Pick) { - return create(options, contentTracer()) +export function createRuntimeContentInstance( + options: Pick, + highlighter: ComarkPlugin, +) { + return create(options, highlighter, contentTracer()) } /** * The throwaway instance the build-time snapshot is parsed with (`modules/snapshot/`). */ -export function createBuildContentInstance(options: Pick) { - return create(options) +export function createBuildContentInstance(options: Pick, highlighter: ComarkPlugin) { + return create(options, highlighter) } diff --git a/utils/highlighter.ts b/utils/highlighter.ts new file mode 100644 index 0000000..270bd4e --- /dev/null +++ b/utils/highlighter.ts @@ -0,0 +1,5 @@ +import rangi from 'comark/plugins/rangi' +import { geistTheme } from './geist.ts' + +/** The code highlighter content is parsed with, unless a site sets `comarkDocs.highlighter`. */ +export default rangi({ theme: geistTheme }) diff --git a/vitest.config.ts b/vitest.config.ts index 35bde04..28264d7 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -1,3 +1,4 @@ +import { fileURLToPath } from 'node:url' import { defineConfig } from 'vitest/config' export default defineConfig({ @@ -5,6 +6,8 @@ export default defineConfig({ test: { projects: [ { + // The alias `modules/config` points at the site's highlighter, here the layer's default. + resolve: { alias: { '#comark-docs/highlighter': fileURLToPath(new URL('utils/highlighter.ts', import.meta.url)) } }, test: { name: 'unit', include: ['test/**/*.test.ts', 'modules/**/*.test.ts', 'scripts/**/*.test.mjs'], From 9a076d9626a36e9d30737166aefe196a7a7efdd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 2 Nov 2026 15:15:00 +0000 Subject: [PATCH 2/3] fix: load the highlighter for the snapshot with jiti and Nuxt's aliases The build-time snapshot imported a custom highlighter with Node's import() outside its try, so a highlighter importing ~/ or an extensionless path failed the whole build. jiti resolves it with Nuxt's aliases, like the runtime bundle, and also loads the layer's own default, so a failure only skips the snapshot. The highlighter test removes its temporary directories. Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30 --- modules/snapshot/index.ts | 26 +++++++++++++------------- package.json | 1 + pnpm-lock.yaml | 3 +++ test/highlighter.test.ts | 10 +++++++--- 4 files changed, 24 insertions(+), 16 deletions(-) diff --git a/modules/snapshot/index.ts b/modules/snapshot/index.ts index 9f13448..334cfcb 100644 --- a/modules/snapshot/index.ts +++ b/modules/snapshot/index.ts @@ -1,15 +1,15 @@ import { mkdir, stat } from 'node:fs/promises' -import { createResolver, defineNuxtModule, useLogger } from '@nuxt/kit' +import type { ComarkPlugin } from 'comark' +import { defineNuxtModule, useLogger } from '@nuxt/kit' import { DEFAULT_CONTENT_NAME } from 'comark-content' import { writeSnapshots } from 'comark-content/build' import fs from 'comark-content/sources/fs' +import { createJiti } from 'jiti' import { join } from 'pathe' import { createBuildContentInstance } from '../../utils/factory' -import defaultHighlighter from '../../utils/highlighter' import { resolveSnapshotSha } from './utils' const logger = useLogger('comark-docs') -const defaultHighlighterPath = createResolver(import.meta.url).resolve('../../utils/highlighter.ts') /** Where the snapshot lives in the build, and the server-asset namespace it is read back through. */ const ASSET_BASE = 'comark-content' @@ -56,17 +56,17 @@ export default defineNuxtModule({ return } - // `withRef` stamps the artifact with the commit. - // At runtime, even with a different commit, we can reuse unchanged bodies. - // The highlighter the runtime parser imports through `#comark-docs/highlighter`. The layer's default is - // imported statically, since Node won't strip types from a `.ts` file in node_modules. - const highlighterPath = nuxt.options.alias['#comark-docs/highlighter']! - const highlighter = highlighterPath === defaultHighlighterPath - ? defaultHighlighter - : (await import(highlighterPath)).default - const content = createBuildContentInstance({ source: fs(contentPath) }, highlighter).withRef(sha) - try { + // The highlighter the runtime parser imports through `#comark-docs/highlighter`, loaded with Nuxt's + // aliases like the bundle resolves it. jiti also transpiles the layer's own `.ts` in node_modules. + const highlighter = await createJiti(import.meta.url, { alias: nuxt.options.alias }).import( + nuxt.options.alias['#comark-docs/highlighter']!, + { default: true }, + ) + // `withRef` stamps the artifact with the commit. + // At runtime, even with a different commit, we can reuse unchanged bodies. + const content = createBuildContentInstance({ source: fs(contentPath) }, highlighter).withRef(sha) + const writeStart = performance.now() await writeSnapshots(content, { dir }) const writeMs = Math.round(performance.now() - writeStart) diff --git a/package.json b/package.json index 2603319..bb7044b 100644 --- a/package.json +++ b/package.json @@ -75,6 +75,7 @@ "defu": "^6.1.7", "exsolve": "^1.1.3", "forges": "^0.3.0", + "jiti": "^2.7.0", "js-yaml": "^5.5.0", "motion-v": "^2.8.0", "nuxt-agent-discovery": "^0.7.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ceb893e..d8ae174 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -262,6 +262,9 @@ importers: forges: specifier: ^0.3.0 version: 0.3.0 + jiti: + specifier: ^2.7.0 + version: 2.7.0 js-yaml: specifier: ^5.5.0 version: 5.5.0 diff --git a/test/highlighter.test.ts b/test/highlighter.test.ts index 2053bb4..81737e3 100644 --- a/test/highlighter.test.ts +++ b/test/highlighter.test.ts @@ -1,4 +1,4 @@ -import { mkdtemp, writeFile } from 'node:fs/promises' +import { mkdtemp, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { expect, it } from 'vitest' @@ -9,8 +9,12 @@ import defaultHighlighter from '../utils/highlighter' async function parse(highlighter: ComarkPlugin) { const dir = await mkdtemp(join(tmpdir(), 'comark-docs-highlighter-')) - await writeFile(join(dir, 'index.md'), '```ts\nconst answer = 42\n```\n') - return JSON.stringify(await createBuildContentInstance({ source: fsSource(dir) }, highlighter).get('/')) + try { + await writeFile(join(dir, 'index.md'), '```ts\nconst answer = 42\n```\n') + return JSON.stringify(await createBuildContentInstance({ source: fsSource(dir) }, highlighter).get('/')) + } finally { + await rm(dir, { recursive: true, force: true }) + } } // `comarkDocs.highlighter` replaces rangi: the plugin a site passes runs, and the default one doesn't. From 018eea23522a87998f2112b62b0783412f2956df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 2 Nov 2026 16:42:07 +0000 Subject: [PATCH 3/3] docs: note what the highlighter cache hash covers Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30 --- modules/config/index.ts | 3 ++- playground/content/1.getting-started/3.configuration.md | 6 +++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/modules/config/index.ts b/modules/config/index.ts index 41cc61e..6dcab67 100644 --- a/modules/config/index.ts +++ b/modules/config/index.ts @@ -228,7 +228,8 @@ export default defineNuxtModule({ ? await resolvePath(options.highlighter, { cwd: rootDir }) : resolve('../../utils/highlighter.ts') nuxt.options.alias['#comark-docs/highlighter'] = highlighter - // A site's highlighter changes the parsed output, so it gets its own content cache namespace. + // A site's highlighter changes the parsed output, so it gets its own content cache namespace. The hash covers + // this file only, not what it imports; the configuration page says so. nuxt.options.runtimeConfig.docs.highlighterVersion = options.highlighter ? createHash('sha256').update(readFileSync(highlighter)).digest('hex').slice(0, 8) : '' diff --git a/playground/content/1.getting-started/3.configuration.md b/playground/content/1.getting-started/3.configuration.md index b96c94d..076c58d 100644 --- a/playground/content/1.getting-started/3.configuration.md +++ b/playground/content/1.getting-started/3.configuration.md @@ -72,7 +72,11 @@ export default defineNuxtConfig({ }) ``` -Install what the file imports in your app, here `comark`, `shiki` and `@shikijs/themes`. Both the build-time snapshot and the runtime parser use it, and the parsed pages are cached under a key that includes a hash of the file, so changing it never serves pages highlighted by the previous one. +Install what the file imports in your app, here `comark`, `shiki` and `@shikijs/themes`. Both the build-time snapshot and the runtime parser use it. + +::note +Parsed pages are cached under a key that includes a hash of this file, so editing it starts a fresh cache. The hash doesn't cover the packages the file imports: after upgrading them, pages already cached keep the previous highlighting for up to 24 hours. Edit the file, even just a comment, to apply the upgrade at once. +:: ### agentDiscovery options