Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions modules/config/index.ts
Original file line number Diff line number Diff line change
@@ -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'
Expand All @@ -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
Expand Down Expand Up @@ -217,6 +223,17 @@ export default defineNuxtModule<ComarkDocsOptions>({
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)
Comment thread
atinux marked this conversation as resolved.
Resolved
: ''
Comment thread
atinux marked this conversation as resolved.
Resolved

// 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!
Expand Down
16 changes: 12 additions & 4 deletions modules/snapshot/index.ts
Original file line number Diff line number Diff line change
@@ -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'
Expand Down Expand Up @@ -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<ComarkPlugin>(
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)
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
28 changes: 28 additions & 0 deletions playground/content/1.getting-started/3.configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
3 changes: 3 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 8 additions & 2 deletions server/utils/cache.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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)
}

/**
Expand All @@ -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. */
Expand Down
12 changes: 8 additions & 4 deletions server/utils/content.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -22,10 +23,13 @@ function getBaseContent(): DocsContent {
}

function createBaseContent() {
return createRuntimeContentInstance({
source: contentSource(),
cache: { driver: contentCacheDriver() },
})
return createRuntimeContentInstance(
{
source: contentSource(),
cache: { driver: contentCacheDriver() },
},
highlighter,
)
}

/**
Expand Down
39 changes: 39 additions & 0 deletions test/highlighter.test.ts
Original file line number Diff line number Diff line change
@@ -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')
})
23 changes: 13 additions & 10 deletions utils/factory.ts
Original file line number Diff line number Diff line change
@@ -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({
Expand All @@ -31,12 +31,12 @@ const comarkPlugins = [
* - The build-time snapshot
* - The runtime instance
*/
function create(options: Pick<ContentOptions, 'source' | 'cache' | 'basePath'>, tracer?: Tracer) {
function create(options: Pick<ContentOptions, 'source' | 'cache' | 'basePath'>, 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 }),
Expand All @@ -48,13 +48,16 @@ function create(options: Pick<ContentOptions, 'source' | 'cache' | 'basePath'>,
}

/** An instance serving requests: traced, and cached per content SHA. */
export function createRuntimeContentInstance(options: Pick<ContentOptions, 'source' | 'cache' | 'basePath'>) {
return create(options, contentTracer())
export function createRuntimeContentInstance(
options: Pick<ContentOptions, 'source' | 'cache' | 'basePath'>,
highlighter: ComarkPlugin,
) {
return create(options, highlighter, contentTracer())
}

/**
* The throwaway instance the build-time snapshot is parsed with (`modules/snapshot/`).
*/
export function createBuildContentInstance(options: Pick<ContentOptions, 'source'>) {
return create(options)
export function createBuildContentInstance(options: Pick<ContentOptions, 'source'>, highlighter: ComarkPlugin) {
return create(options, highlighter)
}
5 changes: 5 additions & 0 deletions utils/highlighter.ts
Original file line number Diff line number Diff line change
@@ -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 })
3 changes: 3 additions & 0 deletions vitest.config.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vitest/config'

export default defineConfig({
oxc: { tsconfig: false } as never,
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'],
Expand Down
Loading