For Content Producers
Write content AI agents can actually use.
Best practices for writing content-md documents — from describing your content clearly in frontmatter to structuring a Markdown body that works well within AI context windows.
Frontmatter
The first ~100 tokens.
The frontmatter block is the first thing an AI agent reads. It decides whether to fetch the full document based on this alone.
Required
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.
Encouraged
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.
Encouraged
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.
Tip
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.
Good frontmatter
✓
---
title: How to Set Up PostgreSQL Connection Pooling with PgBouncer
description: >-
Step-by-step guide to installing and configuring PgBouncer
for transaction-mode pooling on Ubuntu. Covers pool_mode,
max_client_conn, and auth_type settings.
date: 2024-11-02
author: Maria López
license: CC-BY-4.0
---
title: How to Set Up PostgreSQL Connection Pooling with PgBouncer
description: >-
Step-by-step guide to installing and configuring PgBouncer
for transaction-mode pooling on Ubuntu. Covers pool_mode,
max_client_conn, and auth_type settings.
date: 2024-11-02
author: Maria López
license: CC-BY-4.0
---
Avoid
✗
---
title: PgBouncer
description: A post about database connection pooling.
---
title: PgBouncer
description: A post about database connection pooling.
---
Markdown Body
Structure over decoration.
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
<nav> 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
<figure> block with a description, plus a link to the original.Use a nav block for document context
Place a
<nav> 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:
<nav>, <figure>, <abstract>.
Existing Content
Converting what you already have.
You don't need to rewrite your content. content-md layers on top of existing CMS content with minimal changes.
Source
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.
Convert
Strip decorative HTML
Remove navigation bars, sidebars, footers, cookie banners, and ads. Keep the article content. Replace
<img> tags with <figure> blocks containing the alternate text.Serve
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).