Saltar al contenido principal

Writing markdown that AI reads well

AI assistants ingest your docs as markdown. The cleaner your markdown, the more accurately they quote you. Most of this is just good writing — but a few specific choices help noticeably.

One concept per page

When an AI cites a page, it cites the URL. If your page covers three topics, the AI will quote the wrong third in some answers. Split.

A useful test: if you can finish the sentence "This page is about ___" with one noun, the page is right-sized.

Lead with the answer

Most AI assistants quote the first 200 words. If your first paragraph is preamble — "Welcome to this section, where we'll explore..." — that's the part that gets quoted, and it's useless.

Open with the actual answer:

"Custom domains let you publish your docs at docs.yourcompany.com instead of the default docsio.co/yourproject. Free on every plan; SSL is automatic."

Then add context, examples, and edge cases. Don't make readers (or AI) skip past throat-clearing.

Use real markdown structure

This:

## Setup
1. Open project settings.
2. Click "Domains".
3. Add your domain.

| Field | Value |
|---|---|
| Type | CNAME |
| Host | docs |
| Target | docsio.co.cdn.cloudflare.net |

is strictly better than the same thing wrapped in <Steps>, <Card>, or other custom components. Custom components don't render to text the same way for every AI. Standard markdown does.

Use components when they add value visually. Don't use them as decoration around content that would be clearer as plain markdown.

Headings carry semantic weight

AI assistants use H2/H3 hierarchy to figure out what's "main content" vs "asides". One H1 per page (the title), then H2 for top-level sections, then H3 inside those. Don't skip levels (H1 → H3 confuses parsing). Don't use bold-paragraph as a substitute for a heading.

Links should make sense out of context. Compare:

  • Bad: "For details, see the link below."
  • Good: "For DNS troubleshooting, see Custom domains."

When an AI quotes the bad version, the reader has no idea what's being linked to. The good version stands alone.

Code blocks should be runnable

If your docs include a code snippet, it should be ready to paste and run. AI assistants pass code blocks straight to users; subtle issues (placeholder values, missing imports, abbreviated logic) cause real bugs.

If the code is illustrative-only, label it: // pseudocode or # example, not full implementation.

Tables for comparisons

Anything comparison-shaped — plans, options, statuses, error codes — works better as a table than as a paragraph. AI quotes tables wholesale and reproduces them well.

What we don't recommend

  • Long, run-on lists. Bullet points are great for scanning, terrible for reading. If a list has more than 6–7 items, consider splitting into sections.
  • Emojis in headings. They look fun, they break in screen readers, and they confuse some AI parsers. Use Phosphor icons via the sidebar instead.
  • Walls of admonitions. A <Warning> after every paragraph trains readers to ignore them. Reserve admonitions for genuine "you'll regret this if you skip" content.

The shortest test

Open https://docs.yoursite.com/<page>.md in a browser. Read it as plain text. If it's clear, AI assistants will read it well too. If it's confusing, no amount of tooling will fix the writing.