# Markdown Output

Every production build can publish a `.md` file alongside each page's `index.html`. AI crawlers, LLM tools, and programmatic consumers get clean markdown instead of parsing HTML.

## How it works

When `markdownOutput` is enabled in `settings/seo.md`, the build system writes an `index.md` file into every page's output directory:

```text
site/
  index.html          ← your homepage
  index.md            ← markdown version
  docs/
    forms/
      index.html      ← HTML page
      index.md        ← markdown version
    deploy/
      index.html
      index.md
```

Each `.md` file contains the page title as an H1 heading followed by the raw markdown body — no frontmatter, no layout, no HTML wrapper. The content is identical to what you write in your source files.

## Settings

Enable or disable markdown output in `settings/seo.md`:

```yaml
---
# Publish .md versions of every page (for AI crawlers and LLM tools)
markdownOutput: true
---
```

Enabled by default. Set to `false` to skip `.md` file generation.

| Setting | Default | Description |
|---|---|---|
| `markdownOutput` | `true` | Generate `index.md` alongside `index.html` for every page |

Markdown output runs during [activated builds](/docs/build-modes#activated) — the files are written to disk alongside your HTML output.

## What gets generated

Three things happen when markdown output is enabled:

### Per-page .md files

Every page gets a sibling `index.md`. Access it by appending `/index.md` to any page URL:

```text
https://yoursite.com/docs/forms/index.md
https://yoursite.com/blog/my-post/index.md
https://yoursite.com/index.md
```

### llms-full.txt

A single file at `/llms-full.txt` containing the full markdown content of every page on your site, concatenated with page titles and source URLs. This follows the emerging convention for giving LLMs complete site context in one request.

While `/llms.txt` is a table of contents with links, `/llms-full.txt` is the actual content — useful for AI tools that want to ingest your entire site without making multiple requests.

### HTML alternate link

Every HTML page includes a `<link rel="alternate">` tag pointing to its markdown version:

```html
<link rel="alternate" type="text/markdown" href="https://yoursite.com/docs/forms/index.md">
```

This helps AI crawlers discover the markdown version from the HTML page.

## SEO benefits

Markdown output improves AI discoverability in several ways:

- **llms.txt links to .md versions** — when markdown output is enabled, your `/llms.txt` file links directly to the `.md` versions of each page instead of the HTML versions, following the [llms.txt spec](https://llmstxt.org/) recommendation to point to LLM-optimized content
- **llms-full.txt** — a single file with your entire site's content, ready for LLM ingestion
- **`<link rel="alternate">`** — tells crawlers that a markdown version exists
- **Clean content** — AI models get structured text without HTML noise, navigation, footers, or scripts

## Accessing documentation

Markdown output gives AI coding agents access to official sitemd documentation. When an agent needs to know how a feature works, it can fetch the `.md` version of the relevant doc page from sitemd.cc.

```bash
sitemd docs forms           # search docs from the CLI
sitemd docs /docs/deploy    # read a specific doc page
```

## Related pages

- [SEO](/docs/seo) — all SEO features including llms.txt and AI crawler settings
- [Build Modes](/docs/build-modes) — trial vs activated
- [MCP Server](/docs/mcp-server) — all MCP tools