Get started with programmatic SEO

This tutorial builds one search-focused page from a reusable contract. You will scaffold Contentbit, plan the page before its file exists, write the draft, and run the same quality gate an agent or CI job can use later.

You will finish with:

1. A project-wide Contentbit config.
2. A reusable page-family contract.
3. An agent-ready brief for one planned page.
4. A Markdown page that passes strict SEO checks.
5. A local Studio view for reviewing the result.

Only need structured Markdown and rendering? Run contentbit init without --seo, then continue with Render documents.

1. Scaffold the project

Run init with SEO support from the root of an existing React, Astro, or Markdown project:

pnpm dlx contentbit@latest init --seo

npx contentbit@latest init --seo

bunx contentbit@latest init --seo

yarn dlx contentbit@latest init --seo

init detects the framework and package manager, asks a few setup questions, and wires a working content project. Add -y to accept the detected defaults.

The scaffold has two configuration layers:

• contentbit.config.ts tells every command which content, block registry, and SEO config to use.
• contentbit.seo.config.ts describes page families and pages you plan to publish.

The block registry, renderer, example content, Studio script, and agent instructions are ready too. This tutorial focuses on the SEO path first.

The remaining examples use the contentbit binary directly. If your shell does not expose local package binaries, prefix commands with pnpm exec, npx, bunx, or yarn exec.

2. Define one page family

For this tutorial, replace the generated contentbit.seo.config.ts with one small contract:

import { defineSeoConfig } from '@contentbit/core'

export default defineSeoConfig({
  pageTypes: {
    quickstart: {
      requiredFrontmatter: ['type', 'intent', 'keywords.primary'],
      requiredSections: [
        { id: 'overview', headings: ['Overview'] },
        { id: 'workflow', headings: ['Workflow'] },
        { id: 'outcomes', headings: ['Outcomes'] },
      ],
      recommendedBlocks: ['steps'],
    },
  },
  pages: {
    'content/getting-started/safer-content-workflows.md': {
      type: 'quickstart',
      key: 'safer-content-workflows',
      slug: 'safer-content-workflows',
      title: 'Safer content workflows',
      intent: 'product education',
      keywords: {
        primary: 'content workflow',
        secondary: ['content validation', 'AI content workflow'],
      },
    },
  },
})

The quickstart type is the reusable family contract. The entry under pages plans a specific page before its Markdown file exists.

Real projects usually keep several page types, such as alternatives, integrations, comparisons, and glossary entries. Starting with one makes it easy to see what the contract controls.

3. Generate the page brief

Ask Contentbit for the planned page:

contentbit brief safer-content-workflows

The brief combines the target page with its family contract. It includes the primary keyword, required sections, recommended blocks, and acceptance checks.

Use JSON when a coding agent or script will consume the brief:

contentbit brief safer-content-workflows --json

At this point, the plan exists but the content file does not. That is useful: the writer gets the intended structure before drafting rather than trying to repair an arbitrary page afterward.

4. Create the page

Create content/getting-started/safer-content-workflows.md:

---
type: quickstart
intent: product education
keywords:
  primary: content workflow
  secondary: [content validation, AI content workflow]
---

# Safer content workflows

Programmatic content can move quickly without becoming unpredictable. A shared
plan gives each page a clear purpose, repeatable structure, and review process
before anyone starts drafting.

## Overview

A reliable content workflow gives writers and agents the same structure before
they draft and the same checks before they publish. The contract keeps those
requirements visible throughout planning, writing, and review.

## Workflow

:::steps
1. Plan the page with a reusable contract covering its intent, headings, and useful blocks.
2. Generate the brief so the writer understands the target before drafting.
3. Validate the finished content and repair structural problems before review.
:::

## Outcomes

Every page follows the intended structure, uses registered content blocks, and
can be checked locally or in CI. Writers spend less time reconstructing page
requirements, while reviewers get consistent evidence that the draft is ready.

You can also give the brief to an agent instead of writing the file manually:

Write the planned safer-content-workflows page from its Contentbit brief.
Preserve the target facts, satisfy every acceptance check, and run Contentbit
Doctor before you finish.

The installed agent instructions teach supported tools to fetch the live block guide and repair diagnostics without copied schemas in the prompt.

5. Run the quality gate

Check the new page against its family contract:

contentbit doctor content/getting-started/safer-content-workflows.md --strict-seo

Doctor checks the page contract, frontmatter, headings, structured blocks, and general content health in one pass. --strict-seo returns a failing exit code when a required SEO finding remains.

Try changing ## Outcomes to ## Results and run the command again. The report will point to the missing required section. Restore the heading and rerun the gate until it exits cleanly.

6. Review the page in Studio

Open Studio on the same page:

contentbit studio content/getting-started/safer-content-workflows.md

Studio gives you a human view over the same project scan. Open the page to see:

• the rendered preview and source Markdown
• the original SEO brief and acceptance checks
• validation and content-health findings
• keywords, document stats, and block usage

You now have the complete loop: plan, brief, write, inspect, and enforce.

7. Apply the workflow to your project

The tutorial used one small page family and one targeted file. In a real content library, the next step is to classify existing folders with pageDefaults, add planned pages, and run Doctor over the full configured content set.

Continue with:

• Build a programmatic SEO workflow for page defaults, agents, CI, and multilingual projects.
• SEO briefs and contracts for every page-family field.
• Project configuration for shared content, link, registry, and SEO settings.
• Production Astro template when you want a complete multilingual reference implementation instead of wiring the host application yourself.
• LLM-agent integration for the automated writing and repair loop.
• Render documents to publish validated content in React, Astro, or Markdown.
• Content Studio and Content doctor for deeper review and audit options.