=22.18" />

Programmatic SEO · Docs · Playground · Blocks

contentbit

Open-source programmatic SEO toolkit for coding agents.

Define reusable page families, brief writers and agents before they draft, and validate content structure and internal links before publishing. Content stays portable Markdown and renders in React, Astro, or plain Markdown.

• Model page families with required frontmatter, sections, blocks, and links.
• Brief every page before its Markdown file exists.
• Give agents live rules from the same contracts and block registry the CLI checks.
• Enforce quality with ranked Doctor findings and strict CI exit codes.
• Publish anywhere through React, Astro, or plain Markdown adapters.

Quick Start

npx contentbit@latest init --seo

init detects your framework and package manager, installs the right packages, creates the project and SEO configs, wires starter content and a rendered /example page when possible, adds quality scripts, generates the live LLM guide, and installs agent instructions. In Astro projects the example is self-contained and leaves existing content collections untouched.

Plan a page, give the brief to a writer or agent, and run the publishing gate:

contentbit brief        # agent-ready writing contract
contentbit doctor --strict-seo       # content, structure, and link gate
pnpm run studio                      # preview briefs, pages, links, and findings

Or ask the installed coding-agent integration to run the loop:

write the planned  page from its contentbit brief

Only need structured Markdown and rendering? Run contentbit init without --seo.

For a production-shaped Astro implementation, use astro-speedrun-seo. It is the separate reference template for multilingual programmatic SEO, while the small starters in this repository remain compatibility fixtures for package CI.

Prefer the pieces? Install the core packages and a renderer:

pnpm add @contentbit/core @contentbit/blocks @contentbit/react

Why Contentbit

Programmatic content drifts when the plan lives in a spreadsheet, the writing rules live in a prompt, and the quality checks happen during review. Contentbit puts those rules in the codebase so humans, agents, Studio, and CI use the same contract.

import { defineSeoConfig } from '@contentbit/core'

export default defineSeoConfig({
  pageTypes: {
    alternative: {
      requiredSections: ['Overview', 'Comparison', 'FAQ'],
      requiredBlocks: ['comparison'],
      recommendedBlocks: ['faq'],
      minOutgoingLinks: 2,
    },
  },
  pages: {
    'semrush-alternatives': {
      type: 'alternative',
      slug: 'semrush-alternatives',
      intent: 'commercial comparison',
      keywords: { primary: 'semrush alternatives' },
      linksTo: ['seo-tools-comparison'],
    },
  },
})

The page can be briefed before it exists. Once written, Doctor checks the live file against the plan and reports exactly what needs repair.

Structured Markdown underneath

Markdown remains the authoring format. Typed directive blocks add structure where ordinary prose is not enough:

:::comparison{left="Basic" right="Pro"}
- Price | Free | $12/mo
- Support | Community | Priority
:::

Every block has a schema. Invalid content fails with diagnostics a human or model can fix:

article.md:12:1 error CB_PROPS_INVALID
:::callout props invalid: type must be one of note|tip|warning|important|tldr.
hint: Did you mean type="warning"?

The same registry writes the authoring rules the agent sees, so custom blocks, validation, docs, and prompts stay together.

Agent Loop

After init --seo, your agent has a short, repeatable writing loop:

1. Read contentbit.config.ts for the content glob, registry, links, and SEO setup.
2. Run contentbit brief for the target page contract.
3. Run contentbit instructions --audience llm for the live block guide.
4. Write plain Markdown, using blocks only when the guide says they fit.
5. Run contentbit doctor --strict-seo and repair findings until it exits 0.

Refresh or add the integration at any time:

contentbit agents

The installed agent files hold no schemas. They read from the CLI at runtime, so custom blocks are picked up automatically. See the LLM agents guide.

What You Get

File or command	Why it matters
content/example.md	Starter content with built-in blocks and one custom block
blocks/registry.ts	Shared block schemas for validation, renderers, docs, and agents
contentbit.config.ts	Shared content glob, registry, links, and SEO command defaults
contentbit.seo.config.ts	Page-family contracts and plans for existing or future pages
contentbit-guide.md	Generated authoring rules for LLMs
AGENTS.md	Compact instructions for Codex, Cursor, Copilot, and other agents
.claude/skills/*	Claude Code author/audit skills when .claude is present
content:check	Validates content with the right glob and registry
content:doctor	Ranks validation, link, thin-section, and image-alt issues
contentbit brief	Prints an agent-ready SEO brief for an existing or planned page
contentbit snapshot	Prints a portable, JSON-safe project read model for remote adapters
studio	Read-only browser for previews, stats, links, keywords, and health
/example	Rendered route when the detected framework supports it

Render Anywhere

contentbit treats structured Markdown as the portable content format. Use your own prose pipeline for Markdown between blocks, then choose the surface:

• @contentbit/react for React components with headless accessible defaults.
• @contentbit/astro for .astro components with per-block overrides.
• renderToMarkdown() for plain Markdown fallbacks.

The styled React and Astro packs ship through a shadcn registry:

pnpm dlx shadcn@latest add @contentbit/generic-pack

Registry URL: https://contentbit.dev/r/{name}.json.

Content Graph

Use frontmatter to declare relationships and let contentbit keep links honest:

---
slug: beginner-pizza-dough
linksTo:
  - cold-fermentation-pizza
aliases:
  - intro-pizza-dough
---

contentbit links "content/**/*.md" builds .contentbit/link-index.json with resolved links and backlinks. contentbit validate runs link checks when files declare slugs, and contentbit links --fix can rewrite stale alias references. Read the internal linking guide.

Programmatic SEO Contracts

Create contentbit.seo.config.ts with reusable page-type contracts and planned pages, or let contentbit init --seo scaffold a starter. When that file exists, contentbit doctor folds SEO contract findings into the normal repair plan, Studio shows a read-only Brief view for each planned or existing page, and contentbit brief prints the structure, links, required blocks, and acceptance checks an agent should satisfy before publishing. See the programmatic SEO workflow.

Without an agent, the same loop is ordinary CLI-assisted writing: print the brief, write the Markdown, run Doctor, inspect the page in Studio, and publish.

Packages

Package	Purpose
@contentbit/core	Parser, AST, diagnostics, registry, validation, Markdown output
@contentbit/blocks	Generic blocks: callout, steps, comparison, tabs, faq, and more
@contentbit/react	React renderer
@contentbit/astro	Astro renderer
@contentbit/studio	Local read-only content studio
contentbit	CLI: init, validate, doctor, studio, stats, links, render

Explore

• Docs with live-rendered examples
• Compatibility and stability for the v1 public interfaces and upgrade policy
• All blocks from the generic pack
• Playground with live validation
• Blog written as validated contentbit documents
• Changelog for release notes
• llms.txt and the authoring guide for LLM context

Development

pnpm install
pnpm -r build
pnpm -r test
pnpm lint && pnpm fmt:check

See CONTRIBUTING.md for the repo layout and guidelines.

License

MIT