# contentbit (Content Blocks)

> Structured Markdown components without framework lock-in. Authors — humans,
> CMSes, or LLMs — write plain Markdown with directive blocks (:::callout,
> :::comparison, ...). The library parses to a source-mapped AST, validates
> against per-block schemas with file:line:col diagnostics, and renders through
> React, static HTML, or a plain-Markdown fallback. npm scope: @contentbit.
> CLI: `npx contentbit@latest init`.

## Start here

- [Authoring rules](https://contentbit.dev/contentbit-guide.md): the generated block-authoring instructions — paste these into a system prompt before writing Content Blocks documents
- [Full documentation as one file](https://contentbit.dev/llms-full.txt)

## Docs

- [Getting started](https://contentbit.dev/docs): One command to set up Content Blocks — then your coding agent writes validated content.
- [Changelog](https://contentbit.dev/docs/changelog): What shipped in each release.
- [LLM & agent authoring](https://contentbit.dev/docs/concepts/llm-authoring): Generate authoring instructions from the registry, so prompts never drift.
- [Block syntax](https://contentbit.dev/docs/concepts/syntax): The complete directive syntax — fences, props, child blocks, and rows.
- [Why not MDX?](https://contentbit.dev/docs/concepts/why-not-mdx): MDX embeds components. Content Blocks defines a content protocol.
- [Coding-agent integration](https://contentbit.dev/docs/guides/agents): Ship skills and AGENTS.md instructions so any agent can write and audit validated content.
- [Astro](https://contentbit.dev/docs/guides/astro): Render validated documents with .astro components — renderer only, one validation path.
- [Defining custom blocks](https://contentbit.dev/docs/guides/custom-blocks): Add project-specific blocks in under 20 lines with defineBlock.
- [Plug in your Markdown library](https://contentbit.dev/docs/guides/markdown): One function connects Content Blocks to react-markdown, marked, markdown-it, or remark. Step-by-step for each.
- [Renderers](https://contentbit.dev/docs/guides/renderers): Static HTML, React, Astro, and plain-Markdown output from the same document.
- [Document stats & auditing](https://contentbit.dev/docs/guides/stats): analyzeDocument and contentbit stats — outlines, block usage, link domains, and validation summaries as JSON.
- [Block reference](https://contentbit.dev/docs/reference/blocks): Every built-in block, generated from the registry.

## Blog

- [contentbit 0.2.0 — your coding agent writes validated content](https://contentbit.dev/blog/contentbit-0-2-0): One command installs agent skills that fetch the live authoring guide, write, and validate until clean. Plus document stats, an Astro renderer, and fully documented props.
- [Why LLMs write broken Markdown (and how to make it impossible)](https://contentbit.dev/blog/llm-markdown-that-cannot-break): LLMs write Markdown that looks right and breaks in production. Prompting alone never fixes it. A validation contract does.

## Packages

- @contentbit/core: parser, validator, registry, authoring-guide generation
- @contentbit/blocks: the generic block pack
- @contentbit/react: React renderer (headless defaults)
- @contentbit/html: static HTML renderer
- contentbit: CLI — init, validate, stats, render, instructions, agents