Reference

The format, in full.

Complete reference for the content-md document format — frontmatter fields, markdown body rules, and custom block syntax.

The Format

YAML frontmatter, Markdown body.

content-md starts with a YAML frontmatter block (~100 tokens) followed by a Markdown document. Designed to fit within typical AI context windows.

article.md

---
title: Introducing Content-md
description: >-
AI agents should be first-class visitors,
let's give them a tailored experience.
date: 2026-04-29
author: Alessio
license: CC-BY-4.0
---

# Introducing Content-md

AI Agents are increasingly browsing the web on behalf
of humans. The web was built with humans in mind that
demand quality and pleasant interaction. Agents go
straight to the point and prefer a more structured approach.

## The Problem

Converting complex HTML pages with navigation, ads,
and JavaScript into LLM-friendly plain text is both
difficult and imprecise.

---
description: >-
  AI agents must be considered as first-class visitors,
  let's give them a tailored experience.
title:       Introducing Content-md
date:        2024-01-15
author:      Jane Smith
license:     CC-BY-4.0
---

# Introducing Content-md

AI Agents are increasingly browsing the web on behalf of humans...

YAML

Frontmatter

Serves as an introductory summary — ~100 tokens, ~540 characters. AI agents read this first to decide if the full document is relevant before fetching it. Functions as a lightweight preflighted index.

Markdown body

CommonMark or GitHub-flavored Markdown. Must open with a first-level heading. Prefer text over images — link images and include alternate text. Preserve document hierarchy starting from level two.

Frontmatter Fields

The fields.

Field	Required	Description
`title`	Required	Non-empty. The title of the resource — article, page, document.
`description`	Required	Non-empty. Best ~200 characters. A short and accurate summary of the content.
`date`	Encouraged	Date of creation or publication, whichever is more recent. ISO 8601 format.
`license`	Encouraged	License name or SPDX Identifier of the content.
`author`	Encouraged	Author of the content. Host owner is assumed as author if not provided.

Field	Required	Description
`title`	Required	Non-empty. The title of the resource — article, page, document.
`description`	Required	Non-empty. Best ~200 characters. A short and accurate summary of the content.
`date`	Encouraged	Date of creation or publication, whichever is more recent. ISO 8601 format.
`license`	Encouraged	License name or SPDX Identifier of the content.
`author`	Encouraged	Author of the content. Host owner is assumed as author if not provided.

Fields map to Dublin Core, schema.org CreativeWork, and standard HTML meta equivalents.

Custom Blocks

Navigation, figures, and more.

content-md adds a few custom blocks: navigation links, image descriptions, formal abstracts, and ads. AI agents can skip the ad blocks.

<nav> Navigation

Communicate website navigation or linked resources relevant to the content.

<nav>
- Next: [Next article](https://example.com/next)
- Related: [Topic guide](https://example.com/topic)
</nav>

<nav>
- Next: [Next article](https://example.com/next)
- Related: [Topic guide](https://example.com/topic)
</nav>

<figure> Image (alternate)

Include an image's alt text or caption in place of the binary.

<figure>
Alternate text describing the image
and/or its caption for AI context.
</figure>

<figure>
Alternate text describing the image and/or caption
</figure>

<abstract> Abstract

For scientific articles with formal abstracts. The lang attribute is optional.

<abstract lang="en">
We present a novel approach to
serving web content to AI agents...
</abstract>

<abstract lang="en">
We present a novel approach to serving web content to AI agents...
</abstract>

[!AD] Advertisement

Include paid advertisements alongside content — AI agents may choose to ignore them.

> [!AD]
> Buy one, get two — promo active
> for the next 30 days.

> [!AD]
> Buy one, get two — promo active
> for the next 30 days.