comark-content

Universal content layer for Markdown-driven websites. Comark Content turns Markdown from the filesystem, GitHub, or any storage driver into a queryable, searchable, type-safe API. Framework-agnostic, it runs on a server, at the edge, or fully in the browser. Built on Comark.

Why Comark Content

• Runtime-first: read content from its source on demand, or hydrate from a build-time snapshot when the source won't be available in production.
• Lightweight core: three methods — get, list, navigation. Everything else is an opt-in plugin.
• Pluggable sources: filesystem, GitHub, GitLab, Codeberg, and other forges via forges, or any unstorage driver (S3, KV, Redis, HTTP).
• Type-safe: generated types narrow get(), list(), and query() by instance and by path.
• SQL queries & full-text search: opt into a SQLite-backed query builder and BM25 search over frontmatter and content.
• Runs anywhere: Node, edge, or fully in the browser with a hydrated snapshot.
• Framework-agnostic: returns a plain Comark AST, rendered by Vue, React, Svelte, Angular, or plain HTML.

Quick start

pnpm add comark-content

Write a Markdown file:

<!-- content/about.md -->
---
title: About
---

# About us

We write documentation for a living.

Read it:

import { comarkContent } from 'comark-content'
import fs from 'comark-content/sources/fs'

export const content = comarkContent({
  source: fs('./content'),
})

const page = await content.get('/about') // reads ./content/about.md
page?.data.title // 'About'
page?.nodes // parsed body, ready for a Comark renderer

const pages = await content.list() // frontmatter of every page
const nav = await content.navigation() // tree built from your folders

Then render page with a Comark renderer for your framework (@comark/vue, @comark/react, @comark/svelte, @comark/html). The framework guides cover Nuxt, Next.js, SvelteKit, Vite, Nitro, Node, and Hono.

Swap the source for a GitHub repository (with forges), or any unstorage driver — same API:

import forge from 'comark-content/sources/forge'
import { github } from 'forges/github'

const content = comarkContent({
  source: forge({ provider: github(), repo: 'nuxt/nuxt', ref: 'main', path: 'docs' }),
})

Add more when you need it

Everything below is optional. Reach for it when your app has the need.

• Types from your frontmatter. npx comark-content prepare writes comark-content.d.ts, so get('/about') autocompletes and data.title is typed. The Vite plugin does this for you. Add TypeScript types
• Search and queries. Add SQLite (Node or WASM) through a plugin for BM25 full-text search and a fluent query builder over frontmatter. Plugins
• Several sources. Create one instance per source and compose them with contentHub() behind one navigation tree and one handler. Combine content sources
• Deploy without the files. npx comark-content snapshot writes the parsed content so a serverless function or a browser app can serve it with no filesystem. Deploy with a content snapshot
• Remote content that stays current. Read from GitHub, pin a commit, and refresh from a webhook. Keep remote content up to date

CLI

The comark-content binary provides two commands: prepare generates types, and snapshot writes each instance's parsed content.

npx comark-content prepare              # find content.{ts,mts,js,mjs}, write ./comark-content.d.ts
npx comark-content prepare --config server/content.ts -o types/comark-content.d.ts
npx comark-content snapshot             # write .content/<name>/{snapshot,manifest}.json
npx comark-content --help

See the CLI reference for all flags.

Documentation

Full guides, concepts, and API reference at content.comark.dev.

License

Made with ❤️

Published under MIT License.