-
Write content-md
-
Read content-md
-
Specification
+
CLI
+
Write
+
Read
+
Specification
GitHub ↗
diff --git a/source/badge-flat.svg b/source/badge-flat.svg
new file mode 100644
index 0000000..e0022f3
--- /dev/null
+++ b/source/badge-flat.svg
@@ -0,0 +1,14 @@
+
diff --git a/source/badge.svg b/source/badge.svg
new file mode 100644
index 0000000..69f36eb
--- /dev/null
+++ b/source/badge.svg
@@ -0,0 +1,22 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ content-md
+ content-md
+
+
diff --git a/source/cli.blade.php b/source/cli.blade.php
new file mode 100644
index 0000000..697f029
--- /dev/null
+++ b/source/cli.blade.php
@@ -0,0 +1,429 @@
+---
+title: Content-md command line
+description: Command-line tool for browsing and validating content-md sites. Fetch pages as an AI agent, run compliance checks, and convert content to agent skills.
+card:
+ template: '_og.page'
+ path: /assets/og/cli.png
+---
+
+@extends('_layouts.main')
+
+@section('body')
+
+
+ Validate and browse content-md sites
+
+ CLI
+
+
+ A command-line tool for interacting with content-md sites. Fetch pages as an AI agent would, run compliance checks against the spec, and convert content into agent skills.
+
+
+
+
+
+
+
+
+
+
+
+{{-- Browse --}}
+
+
+ Browse
+
+ Fetch pages like an AI agent.
+
+ The default command sends Accept: text/markdown and prints the content-md response. Falls back to HTML on 406. Works with single URLs, lists, or entire sitemaps.
+
+
+
+
+
+
+
+
Single page
+
+
+
+ contentmd https://contentmd.org/specification/
+
+
+
+
+
+
Multiple pages → folder
+
+
+
+ contentmd --output ./pages \
+ https://contentmd.org/specification/ \
+ https://contentmd.org/consumers/
+
+
+
+
+
+
Full site via sitemap
+
+
+
+ contentmd --sitemap --output ./pages \
+ https://contentmd.org
+
+
+
+
+
+
+
+
+
+ | Flag |
+ Description |
+
+
+
+
+ --agent |
+ Raw markdown only, no size/token header |
+
+
+ --sitemap |
+ Fetch /sitemap.xml and iterate every URL in it |
+
+
+ --output <folder> |
+ Save each response as a .md file (required for multiple URLs) |
+
+
+ --frontmatter-only |
+ Send Range: x-frontmatter to fetch only the frontmatter |
+
+
+ --follow-redirect |
+ Follow HTTP redirects (reported as errors by default) |
+
+
+
+
+
+
+
+
+ | Flag | Description |
+
+
+ --agent | Raw markdown only, no size/token header |
+ --sitemap | Fetch /sitemap.xml and iterate every URL in it |
+ --output <folder> | Save each response as a .md file |
+ --frontmatter-only | Fetch only the frontmatter via Range header |
+ --follow-redirect | Follow HTTP redirects |
+
+
+
+
+
+
+
+
+
+{{-- Validate --}}
+
+
+ Validate
+
+ Check compliance against the spec.
+
+ The validate subcommand runs a full compliance report against a URL — content negotiation, caching headers, frontmatter fields, document structure, and more. Every check is rated pass, warn, or fail, with a score from 0 to 100.
+
+
+
+
+
+
+
+
+
+ | Check |
+ What it verifies |
+
+
+
+
+ content-negotiation |
+ Server returns text/markdown for Accept: text/markdown |
+
+
+ vary-accept |
+ Response includes Vary: Accept |
+
+
+ frontmatter-title |
+ title field present and non-empty |
+
+
+ frontmatter-description |
+ description field present and non-empty |
+
+
+ heading-h1 |
+ Markdown body starts with an H1 |
+
+
+ frontmatter-tokens |
+ Frontmatter is within the ~100 token budget |
+
+
+ range-frontmatter |
+ Range: x-frontmatter returns only the frontmatter block |
+
+
+ title-html-match |
+ Frontmatter title matches the HTML <title> |
+
+
+
+
And 9 more checks — heading hierarchy, link headers, robots.txt, sitemap presence, description length, and more.
+
+
+
+
+
+ | Check | What it verifies |
+
+
+ content-negotiation | Server returns text/markdown for Accept: text/markdown |
+ vary-accept | Response includes Vary: Accept |
+ frontmatter-title | title field present and non-empty |
+ frontmatter-description | description field present and non-empty |
+ heading-h1 | Markdown body starts with an H1 |
+ frontmatter-tokens | Frontmatter within ~100 token budget |
+ range-frontmatter | Range: x-frontmatter returns only the frontmatter |
+ title-html-match | Frontmatter title matches HTML title element |
+
+
+
+
+
+
+
+
+
Plain output (default)
+
+
+
+contentmd validate https://contentmd.org/specification/
+
+Validating https://contentmd.org/specification/ ...
+
+ ✓ content-negotiation
+ ✓ vary-accept
+ ✓ frontmatter-title
+ ✓ frontmatter-description
+ ✓ heading-h1
+ ✓ frontmatter-tokens
+ ! link-header — Link header not found
+ ! html-alternate-link — rel=alternate not set
+
+Score: 87/100
+
+
+
+
+ Use --format json for structured output — useful in CI pipelines or when comparing reports over time.
+
+
contentmd validate --format json https://contentmd.org/
+
+
+
+
+
+ Save a baseline report with --save baseline.json and compare it later. Useful for tracking compliance regressions as a site evolves.
+
+
contentmd validate --save baseline.json https://contentmd.org/
+
+
+
+
+
+ Use --format markdown to generate a compliance table suitable for posting in pull request comments.
+
+
contentmd validate --format markdown https://contentmd.org/
+
+
+
+
+
+
+
+
+
+{{-- Skill + Agent mode --}}
+
+
+ More
+
+ Skills and agent mode.
+
+ Two more built-in features: convert any content-md page into an agent skill file, and a detection mechanism that lets AI coding agents use the CLI without extra flags.
+
+
+
+
+
+
+ contentmd skill
+ Convert to agent skill
+
+
Converts a content-md page into an Agent Skill (SKILL.md) — remapping frontmatter fields and adding a source: URL reference.
+
+
+
Skill command
+
+
+
+ contentmd skill https://contentmd.org/specification/
+
+ # Write to a file
+ contentmd skill --output SKILL.md https://contentmd.org/specification/
+
+
+
+
+
+
+ --agent
+ Agent mode
+
+
All three commands support --agent. When active, output is stripped of human-readable formatting: raw markdown for browse, JSON for validate, and a structured object for skill.
+
+ Agent mode is implied automatically when coding agent environment variables are set — CLAUDE_CODE, CURSOR_AGENT, GEMINI_CLI, CODEX_SANDBOX, and more. No flag needed when running inside an AI coding agent.
+
+
+
+
+
+
+
+
+@endsection
+
+@push('markdown')
+
+# contentmd CLI
+
+Command-line tool for browsing and validating content-md formatted web resources — fetch URLs as an AI agent, check compliance, and convert pages to skills.
+
+## Install
+
+Pre-built binaries for Linux, macOS, and Windows are available on [GitHub Releases](https://github.com/OneOffTech/contentmd/releases). No runtime required.
+
+## Browse
+
+Fetch a URL as an AI agent would — requesting `text/markdown` via content negotiation, falling back to HTML on 406.
+
+```sh
+contentmd https://contentmd.org/specification/
+
+# Multiple pages saved to a folder
+contentmd --output ./pages https://contentmd.org/specification/ https://contentmd.org/consumers/
+
+# Entire site via sitemap
+contentmd --sitemap --output ./pages https://contentmd.org
+```
+
+| Flag | Description |
+| --- | --- |
+| `--agent` | Raw markdown only, no size/token header |
+| `--sitemap` | Fetch `/sitemap.xml` and iterate every URL in it |
+| `--output
` | Save each response as a `.md` file |
+| `--frontmatter-only` | Send `Range: x-frontmatter` to fetch only the frontmatter |
+| `--follow-redirect` | Follow HTTP redirects (reported as errors by default) |
+
+## Validate
+
+Check that a URL correctly serves content-md and report compliance.
+
+```sh
+contentmd validate https://contentmd.org/specification/
+```
+
+Each check is rated **pass**, **warn**, or **fail**. The report includes a **score from 0 to 100**.
+
+| Check | What it verifies |
+| --- | --- |
+| `content-negotiation` | Server returns `text/markdown` for `Accept: text/markdown` |
+| `vary-accept` | Response includes `Vary: Accept` |
+| `frontmatter-title` | `title` field present and non-empty |
+| `frontmatter-description` | `description` field present and non-empty |
+| `heading-h1` | Markdown body starts with an H1 |
+| `frontmatter-tokens` | Frontmatter within ~100 token budget |
+| `range-frontmatter` | `Range: x-frontmatter` returns only the frontmatter |
+| `title-html-match` | Frontmatter title matches HTML `` |
+
+And 9 more checks — heading hierarchy, link headers, robots.txt, sitemap presence, description length, and more.
+
+### Output formats
+
+```sh
+# Machine-readable JSON
+contentmd validate --format json https://contentmd.org/
+
+# Save a baseline for later comparison
+contentmd validate --save baseline.json https://contentmd.org/
+
+# Markdown table for CI comments
+contentmd validate --format markdown https://contentmd.org/
+```
+
+## Skill
+
+Convert a content-md page into an [Agent Skill](https://agentskills.io) (`SKILL.md`).
+
+```sh
+contentmd skill https://contentmd.org/specification/
+
+# Write to a file
+contentmd skill --output SKILL.md https://contentmd.org/specification/
+```
+
+## Agent mode
+
+All three commands support `--agent`. When active, output is stripped of human-readable formatting — raw markdown for browse, JSON for validate, a structured object for skill.
+
+Agent mode is auto-detected from coding agent environment variables: `CLAUDE_CODE`, `CURSOR_AGENT`, `GEMINI_CLI`, `CODEX_SANDBOX`, and more. No flag needed when running inside an AI coding agent.
+
+@endpush
diff --git a/source/index.blade.php b/source/index.blade.php
index 8d57002..ef0be2b 100644
--- a/source/index.blade.php
+++ b/source/index.blade.php
@@ -64,6 +64,12 @@
+
+ Browse and validate content-md sites from the command line — fetch pages as an AI agent, run compliance checks, and convert content to agent skills.
+
+ CLI reference →
+
+
Serve pre-existing markdown files via the Caddy web server with proper content negotiation headers built in.
@@ -117,6 +123,47 @@
+
+{{-- Badges --}}
+
+
+ Badges
+
+ We have badges too
+
+ Add a badge to show that your project or site serves content-md.
+
+
+
+
+
+
+

+
+
Markdown
+
[](https://contentmd.org)
+
HTML
+
<a href="https://contentmd.org"><img src="https://contentmd.org/badge.svg" alt="Supports content-md format for AI Agents"></a>
+
+
+
+
+

+
+
Markdown
+
[](https://contentmd.org)
+
HTML
+
<a href="https://contentmd.org"><img src="https://contentmd.org/badge-flat.svg" alt="Supports content-md format for AI Agents"></a>
+
+
+
+
+
Standard: [](https://contentmd.org)
+
Flat: [](https://contentmd.org)
+
+
+
+
@@ -150,6 +197,7 @@
- **Caddy Content Negotiation**: Serve pre-existing markdown files via the Caddy web server with proper content negotiation headers built in. [avvertix/caddy-content-negotiation](https://github.com/avvertix/caddy-content-negotiation/)
- **WordPress Post to Markdown**: Serve post content as Markdown directly from Wordpress. [roots/post-content-to-markdown](https://github.com/roots/post-content-to-markdown)
+- **contentmd CLI**: Browse and validate content-md sites from the command line — fetch pages as an AI agent, run compliance checks, and convert content to agent skills. [CLI reference](/cli)
## Comparison
@@ -165,6 +213,20 @@
Skills provides additional knowledge to agents, currently within dedicated folders. content-md responses are nearly compatible with Skills; the frontmatter fields map closely.
+## Badges
+
+Promote the usage of content-md via the badge.
+
+Standard badge:
+```
+[](https://contentmd.org)
+```
+
+Flat badge:
+```
+[](https://contentmd.org)
+```
+