---
title: 'content-md Specification'
description: 'Content-md specification with frontmatter fields and custom block syntax.'
date: 2026-05-05
license: 'CC-BY-4.0'
---


# content-md Specification

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

## The Format

content-md starts with a YAML frontmatter block (~100 tokens) followed by a Markdown document.

### Frontmatter

An introductory summary: ~100 tokens, ~540 characters. AI agents read this first to decide whether to fetch the full document. A lightweight content 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

| 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

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

### Navigation

Communicate website navigation or linked resources relevant to the content.

```

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

```

### Image (alternate)

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

```

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

```

### Abstract

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

```

We present a novel approach to serving web content to AI agents...

```

### 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.
```



- [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)