blog.dopana

Back

You write docs for humans, then an AI agent reads them every day and pays tokens for every star, every extra space. Sound familiar?

The problem: Markdown was designed to look nice for people. LLMs do not need pretty, they need compact, well structured, easy to extract by section. agent-md fixes exactly that: a Rust CLI that makes Markdown friendly for LLMs, saves tokens, and stays readable for humans.

What Is Agent-md?#

Explain like you are 10: imagine packing lunch for a friend. Humans like a fancy box with many decorated compartments, robots just want one compact box with clear labels where each compartment opens directly. agent-md packs that lunchbox for robots.

Concretely, agent-md is:

  • A fast Rust CLI that formats and lints Markdown for AI agents, single binary
  • A Rust library (agent_md) with format_markdown, parse_markdown, validate_markdown
  • A VS Code extension called Agent-MD Formatter, with format on save
  • Every command returns JSON for easy LLM parsing, plus a --human flag for people

Current version is 0.2.16, install with cargo install agent-md or build from source.

Why Normal Markdown Wastes Tokens?#

LLM-generated Markdown is often wasteful:

  • Decorative bold **bold** and italic markers add no meaning for machines
  • Wide tables with long separators |----------| instead of |---|
  • Comments in code blocks with many spaces: bun dev # run server
  • Repeated blank lines, horizontal rules ---, 4-space indents in normal text
  • Useless links like [https://example.com](https://example.com)
  • Diagrams drawn with box characters and sketchy folder trees, hard to parse

Every time an LLM reads the file, you pay a token tax for that decoration. Across a repo with many docs, it adds up fast.

How Does Agent-md Work?#

It is not a simple line formatter. agent-md uses structured parsing:

Markdown inputSplit YAML frontmatterDetect blocks: heading, table,list, code, HTMLFormat each block by typeLint with 17 rulesCompact output, JSON ifneeded

Main steps:

  1. Preserve YAML frontmatter at the top exactly
  2. Detect each block: headings, code, tables, lists, HTML, paragraphs
  3. Format each type with context-aware, token-saving rules
  4. Validate with the linter, return JSON with valid, errors, warnings

Agent-md Writing Rules#

The linter has 17 rules in two groups. Errors block file writes, warnings should be fixed.

Common error rules:

  • no-bold: no **bold** or __bold__ outside code, see example below
  • simple-table: max 5 columns, separator must be |---|, strip alignment colons
  • table-trailing-spaces: no extra trailing spaces inside table cells
  • no-ascii-graph: no box-character diagrams, use CSV, JSON, Mermaid, or lists
  • heading-structure: single H1, no skipped levels from H1 to H3
  • code-blocks: code needs a language tag and a closing fence
  • list-formatting: consistent markers, no empty items
  • space-indentation: max 2 spaces in normal text, code is exempt
  • no-useless-links: link text must differ from the URL

Example for the no-bold rule:

This line fails because it has double stars.
Replace with plain text, or use a heading, or use code.
Code blocks may keep their original syntax.
text

Warning rules cover duplicate headings, multiple blank lines, missing blanks around headings, missing H1 at the top, missing final newline, hard tabs, and trailing spaces.

Full details live in docs/markdown-writing-rules.md in the source repo.

Install#

cargo install agent-md

# Or build from source
cargo build --release
# Binary at target/release/agent-md

# Use as Rust library
# Cargo.toml: agent-md = "0.2.16"
bash
use agent_md::{format_markdown, validate_markdown};

let input = "# Heading\n\nSome text with *emphasis*.";
let formatted = format_markdown(input);
let result = validate_markdown(&formatted);
assert!(result.valid);
rust

Real Use: Format and Lint#

Format one file or a whole directory, respecting .gitignore and .markdownlintignore:

agent-md README.md
agent-md fmt README.md
agent-md fmt .

# Inspect resolved config for a file
agent-md config path/to/document.md

# Inspect merged ignore rules
agent-md ignore
bash

Lint returns JSON so agents can read it directly:

agent-md lint README.md
agent-md --human lint README.md
agent-md lint --content "# Title\nContent here"
agent-md lint-file README.md
bash

Example output when a file passes:

{
  "valid": true,
  "errors": [],
  "warnings": []
}
json

Before and after for tables:

 | Function | Arguments | Return Type | Description |
-|----------|-----------|-------------|-------------------------------|
-| `add()`  | a, b      | i32         | Adds two numbers              |
+|---|---|---|---|
+| `add()` | a, b | i32 | Adds two numbers |
diff

Comments in code blocks get collapsed spaces:

-bun i                      # Install dependencies
-bun run dev                # Run the development server
+bun i # Install dependencies
+bun run dev # Run the development server
diff

By default the formatter also strips bold markers, compacts blank lines, collapses spaces, removes horizontal rules, removes emphasis, minifies HTML to one line, adds text to unlabeled code blocks, drops empty list items, and normalizes list indent to 2 spaces.

Read One Section, Not the Whole File#

This is the best feature for agents: no need to read a 700-line README to get one section.

Suggested agent workflow:

# 1. Get structure
agent-md read README.md --field headings

# 2. Find what to change
agent-md search README.md "TODO"

# 3. Validate before writing
agent-md lint --content "# New Title\nValid content"

# 4. Write with validation
agent-md write README.md "# New Title\nValid content"

# 5. Replace one section only
agent-md write-section README.md --section "## Development" --content "New content"
bash

Other write commands: write, append, insert, delete, write-section, list. The write command validates first, so it is hard to create off-spec files.

Plug Into Your Agent Workflow#

Add one line to AGENTS.md and agents follow it:

After creating or updating any markdown file, always run agent-md lint path/to/file.md to validate before done.
On task completion, update docs, update README.md, and write unit tests.
text

Or tell agents briefly: use the agent-md CLI for reading, writing, and editing Markdown instead of direct file edits. The source repo has docs/llm-agent-rule.md with full integration guidance.

For VS Code, install Agent-MD Formatter and enable format on save for Markdown:

{
  "[markdown]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "agent-md.agent-md-formatter"
  }
}
json

[!TIP] Run agent-md fmt before committing LLM-generated docs. You keep all information, cut about 20% tokens in many cases, LLMs read faster and you pay less.

When Not to Use It?#

  • Docs made for beautiful human printing with fancy table alignment: keep the human version, generate a compact agent version
  • ASCII diagrams as team culture: move to Mermaid so both humans and machines can read
  • Files already valid: if lint says valid, no need to reformat

References#