--- title: 'content-md for writers' description: 'Best practices and guidelines for writing content-md documents — how to structure frontmatter, markdown body, and custom blocks for optimal AI agent consumption.' date: 2026-05-05 license: 'CC-BY-4.0' --- # content-md for Content Producers How to write content-md documents: structuring frontmatter, markdown body, and custom blocks. ## Frontmatter The frontmatter block is the first thing an AI agent reads. It decides whether to fetch the full document based on this alone. ### Write a precise description Get the `description` right. Aim for ~200 characters. Be specific: avoid phrases like "a blog post about X" and state what the reader will actually get from the content. ### Always include a date AI agents use `date` to assess freshness. A guide from 2019 may have outdated advice; an agent that knows this can deprioritise it accordingly. Use ISO 8601: `2024-03-15`. ### Declare a license The `license` field tells agents how your content may be used. Use an SPDX identifier like `CC-BY-4.0` or `CC-BY-NC-4.0`. Omitting it leaves agents without guidance on permissible use. ### Keep frontmatter within ~540 characters The frontmatter fits in ~100 tokens. Beyond that it stops being a lightweight index and starts eating into the agent's context budget. Keep field values concise. ## Markdown Body The markdown body is what agents read and reason over. Poor structure leads to worse answers. ### Open with a level-one heading The first line of the body must be an `# H1` heading matching the document title. ### Use headings to create a scannable outline Agents scan heading structure before reading in full. Use `##` for main sections and `###` for subsections. Don't skip levels: jumping from `##` to `####` creates a broken hierarchy. ### Prefer prose over tables for heavy content Tables work well for reference data (fields, parameters, options). For explanatory content, plain paragraphs are easier to parse. Don't convert prose into tables just to look structured. ### Keep the document within a reasonable token budget Aim for under 4,000 tokens (~16,000 characters). Very long documents may exceed an agent's working context. If your content is long, link to sub-pages from a `` block rather than cramming everything into one file. ### Replace images with text descriptions Binary image embeds don't work in a text response. For decorative images, omit them. For informational images (charts, diagrams, screenshots) use a `` block with a description, plus a link to the original. ### Use a `` block for document context Place a `` block near the top or bottom of the document (not inside section headings) linking to previous/next pages, a table of contents, or related resources. ### Use code blocks for all code Fence code samples with triple backticks and a language identifier: ` ```python `, ` ```bash `, etc. Use inline code for identifiers, commands, and values. ### Avoid HTML Inline HTML adds noise. Stick to plain markdown and the defined content-md blocks: ``, ``, ``. ## Converting Existing Content You don't need to rewrite your content. content-md layers on top of existing CMS content with minimal changes. ### 01 — Start with your title and excerpt Most CMS platforms already store a title, excerpt or meta description, publication date, and author. These map directly to frontmatter fields with no extra writing. ### 02 — Strip decorative HTML Remove navigation bars, sidebars, footers, cookie banners, and ads. Keep the article content. Replace `` tags with `` blocks containing the alternate text. ### 03 — Use a plugin or generate on publish Generate the content-md file at publish time and serve it via content negotiation (e.g. Caddy module) or integrate it into your CMS (e.g. Wordpress). - [Write content-md](https://contentmd.org/writers) - [Read content-md](https://contentmd.org/consumers) - [Reference](https://contentmd.org/reference) - [GitHub ↗](https://github.com/OneOffTech/contentmd)