diff --git a/modules/config/index.ts b/modules/config/index.ts index da1c679..6dcab67 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,17 @@ 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. 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) + : '' + // 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..334cfcb 100644 --- a/modules/snapshot/index.ts +++ b/modules/snapshot/index.ts @@ -1,8 +1,10 @@ import { mkdir, stat } from 'node:fs/promises' +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 { resolveSnapshotSha } from './utils' @@ -54,11 +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. - const content = createBuildContentInstance({ source: fs(contentPath) }).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/playground/content/1.getting-started/3.configuration.md b/playground/content/1.getting-started/3.configuration.md index f0043e5..076c58d 100644 --- a/playground/content/1.getting-started/3.configuration.md +++ b/playground/content/1.getting-started/3.configuration.md @@ -45,11 +45,39 @@ 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. + +::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 [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/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/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..81737e3 --- /dev/null +++ b/test/highlighter.test.ts @@ -0,0 +1,39 @@ +import { mkdtemp, rm, 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-')) + 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. +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'],