Comark Content is a Markdown-only content module for Nuxt, powered by Comark.

Markdown is parsed at build time and written as compressed server assets. No database runs, and no Markdown is parsed while a request is in flight.

Status: experimental. APIs may change before the first release.

Features

• 📄 Build-time Markdown: page Collections are parsed once and shipped as gzip server assets.
• 🌍 Local and remote sources: globs from your content directory, or a Git repository pinned to a branch or tag.
• 🔎 One query API: queryCollection and friends run the same way in the browser and inside Nitro.
• 🗜️ Lazy decompression: a filtered query reads the metadata index only, then loads bodies for matched documents.
• 🎨 Rangi highlighting: GitHub Light and Dark by default, with extra grammars bundled and your own themes accepted.
• 🗺️ Sitemap aware: @nuxtjs/sitemap reads Collections through the manifest and lists them as its own data source.

Installation

npx nuxi@latest module add @harlan-zw/comark-content

[!TIP] Generate an Agent Skill for this package using skilld:

npx skilld add @harlan-zw/comark-content

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@harlan-zw/comark-content'],
})

The module reads the content configuration key.

Boundary

The module supports page collections of Markdown files only.

| Supported | Not supported | | --- | --- | | Local Markdown, include and exclude globs, collection prefixes | Data collections, YAML, JSON, CSV sources | | Remote Git repositories with branch, tag, and token auth | Provider APIs and write access | | Standard Schema frontmatter parsing | Schema library re-exports | | Query, navigation, surroundings, search sections, sitemap entries | Raw SQL, count, skip, mutation | | Rangi code highlighting | Shiki, MDC nodes, @nuxtjs/mdc, runtime Markdown parsing |

If you configure database, the build fails with an explicit error.

Collections

Declare collections in content.config.ts at the root of any layer.

// content.config.ts
import { defineCollection, defineContentConfig } from '@harlan-zw/comark-content'
import { z } from 'zod'

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: { include: 'docs/**/*.md', prefix: '/docs' },
      schema: z.object({
        publishedAt: z.string().optional(),
      }),
    }),
  },
})

Every layer may declare collections. Each name must be unique across all layers. If two files declare one name, the build fails and names both files.

Local sources resolve against the content directory of the layer that declares them. Set cwd to read from another directory.

Remote sources

defineCollection({
  type: 'page',
  source: {
    include: 'docs/content/**/*.md',
    prefix: '/modules/og-image',
    repository: {
      url: 'https://github.com/nuxt-modules/og-image',
      tag: 'v5.1.14',
      auth: { token: process.env.GITHUB_TOKEN },
    },
  },
})

The checkout directory is keyed by repository URL and reference. A tag never moves, so its checkout is cloned once and then reused. A branch, or no reference, is cloned again on every full build. Local Markdown edits during development never trigger a clone.

If a clone with a token fails, the module retries once without the token. If the retry fails, the build fails. Stale content is never served after a failed refresh.

Querying

The same functions run in the browser and on the server.

<script setup lang="ts">
const { data: page } = await useAsyncData('page', () => {
  return queryCollection('docs').path('/docs/getting-started').first()
})

const { data: navigation } = await useAsyncData('navigation', () => {
  return queryCollectionNavigation('docs')
})
</script>

Available functions:

• queryCollection(name) with path, where, select, order, limit, all, and first
• queryCollectionNavigation(name, fields?)
• queryCollectionItemSurroundings(name, path, options?)
• queryCollectionSearchSections(name)

where supports the =, LIKE, <>, and IS NULL operators.

Import the same functions from @harlan-zw/comark-content/server inside Nitro handlers. The server versions take the request event as their first argument.

// server/api/page.get.ts
import { queryCollection } from '@harlan-zw/comark-content/server'

export default defineEventHandler(async (event) => {
  return queryCollection(event, 'docs').path('/docs').first()
})

Only the metadata index is decompressed for a filtered query. Document bodies load one at a time, and only for matched documents.

Rendering

<template>
  <ContentRenderer v-if="page" :value="page" />
</template>

ContentRenderer renders Comark nodes as semantic HTML. It resolves an HTML tag to ContentProseX, then ProseX. It resolves a custom tag to ContentX, ProseX, then X. Components in app/components/content are also available under their unprefixed name. Only tags present in the parsed content are imported.

Set unwrap="p" to render slot content without its paragraph wrapper.

The content:file:beforeParse and content:file:afterParse Nuxt hooks run around each document.

Highlighting

Code highlighting is on by default and uses Rangi. The bundled theme pair is GitHub Light and GitHub Dark, with an AA contrast comment color. The bundled extra languages are dotenv, env, robots, robots-txt, and robots.txt.

export default defineNuxtConfig({
  content: {
    highlight: {
      theme: { light: myLightTheme, dark: myDarkTheme },
      languages: { hcl: myHclGrammar },
    },
  },
})

To turn highlighting off, set highlight: false. The Rangi stylesheet is then not added to your application.

Import the bundled theme and languages to extend them:

import { contentRangiLanguages, contentRangiTheme } from '@harlan-zw/comark-content'

AST helpers

Two helpers read parsed Markdown nodes:

import { nodeToText, walkNodes } from '@harlan-zw/comark-content'

const title = nodeToText(page.body.nodes[0])

walkNodes(page.body.nodes, (node) => {
  if (typeof node !== 'string' && node[0] === 'img')
    images.push(node[1].src)
})

Sitemap

@nuxtjs/sitemap 8.4.0 or later owns this integration. It reads collections through queryCollectionManifest() and lists them under its own data source, @harlan-zw/comark-content:urls. An older @nuxtjs/sitemap is rejected at build time, because this module used to add the URLs itself and the pair would list every page twice.

A page is skipped when its frontmatter sets sitemap: false or robots: false. Frontmatter sitemap object fields are merged into the entry. The entry lastmod comes from seo.articleModifiedTime, or from updatedAt.

To keep a whole collection out of the sitemap, set sitemap: false on the collection:

snippets: defineCollection({
  type: 'page',
  source: 'snippets/**/*.md',
  sitemap: false,
})

Deployment

Parsed collections are written as gzip server assets. Navigation, surroundings, and search use content-addressed GET routes. The route key hashes the parsed content only. A redeploy that changes no content keeps the same routes, so clients running the previous build keep working.

Cloudflare presets require @harlan-zw/nuxt-cloudflare with Workers Caching enabled. The build fails otherwise.

Sponsors

License

Licensed under the MIT license.