Comark Content vs headless CMS
TL;DR: A headless CMS (Contentful, Sanity, Strapi, ...) hosts your content in its database, behind its API, with an editing UI on top. Comark Content is not a hosted service: it's a library that turns Markdown you already own — in a repo, a bucket, or a KV store — into the same kind of queryable, typed API. If your content is written by developers or technical writers in Markdown, you usually don't need a headless CMS. If non-technical editors need a browser UI, workflows, and roles, you do.
At a glance
| Comark Content | Headless CMS (Contentful, Sanity, ...) | |
|---|---|---|
| What it is | Open source library | Hosted service (SaaS) |
| Content lives in | Your repo, bucket, KV, or database | The vendor's database |
| Content format | Markdown with components | Proprietary rich text (Portable Text, Contentful Rich Text) |
| Editing | Any editor, git workflow, PRs and reviews | Browser editing UI, roles, workflows |
| Cost | Free | Free tier, then per-seat / per-record / per-request pricing |
| API limits | None — it runs in your process | Rate limits per plan |
| Delivery | In-process reads, cache, or HTTP handler | CDN-backed delivery API |
| Versioning | Git history for free (diffs, blame, revert) | Vendor version history |
| Migration out | Your files are already Markdown | Export from proprietary formats |
| Querying | list(), optional SQL queries | Vendor query language (GROQ, GraphQL, REST filters) |
| Search | Optional BM25 full-text search | Vendor search endpoints or add-ons |
The core difference
A headless CMS answers "where does content live and who edits it" by taking ownership: content moves into the vendor's database, editors work in the vendor's UI, and your app fetches JSON over the vendor's API. That's the right trade when a marketing team publishes daily and no one wants to touch git.
Comark Content answers the same question without moving your content. Markdown files stay where they are; the library indexes and serves them:
import { comarkContent } from 'comark-content'
import github from 'comark-content/sources/github'
const content = comarkContent({
// Content team pushes Markdown to this repo. No rebuild, no Content bill.
source: github({ repo: 'my-org/content', branch: 'main' }),
})
const post = await content.get('/blog/launch')You keep git as the editing workflow: branches for drafts, PRs for review, history for auditing, revert for rollbacks. Rich text stays portable — it's Markdown, readable by every tool, including LLMs.
What a headless CMS gives you that Comark Content doesn't
Be honest about the trade:
- An editing UI. Comark Content has no browser editor. Editors work in Markdown via GitHub's web editor, a git client, or any Markdown app writing to your storage.
- Roles and workflows. Approval chains, scheduled publishing, and per-field permissions are vendor features. With Comark Content you model these with git (protected branches, PR reviews, CI).
- Structured non-document content. Product catalogs with hundreds of relational fields fit a database-backed Content better than frontmatter. Comark Content handles structured entries via the JSON and YAML plugins, with schema validation — good for settings, authors, or navigation, not for relational datasets.
What Comark Content gives you that a headless CMS doesn't
- Ownership. Content is files in storage you control. No export project when you leave.
- Zero marginal cost. No seats, no record counts, no API metering.
- No network dependency in the hot path. Reads come from your process and cache, not a third-party API. It also runs fully in the browser.
- Markdown-native components.
::alert{type="info"}lives in the content itself and renders through Vue, React, Svelte, or HTML — no rich-text-to-component mapping layer. - A git audit trail. Every change is a commit with an author and a diff.
When to pick which
Pick a headless CMS when non-technical editors publish frequently, need previews and workflows in a browser, and the content model is deeply relational.
Pick Comark Content when content is Markdown written by people comfortable with git or files: documentation, blogs, marketing sites, changelogs, knowledge bases — and you want typed access, search, and queries without a service in the middle.
FAQ
Is Comark Content a git-based Content?
It's source-agnostic. Git (via the GitHub source) is the most common setup, but the same API reads from the filesystem, S3, KV, Redis, or a custom backend.
Can editors preview changes before publishing?
Yes, with git branches: point a preview deployment's source at the branch, merge to publish. This site does exactly that — any branch or commit is viewable live.
Can I put an editing UI on top of Comark Content?
The Content instance exposes update() and remove() plus an HTTP handler, so you can build editing flows against it. A ready-made editor UI is not part of the library.
Is it really free?
Yes. MIT-licensed open source. Your only costs are your own hosting and storage.