---
title: "Markdown and llms.txt"
description: "Every page of these docs as Markdown, with its examples, options and the theme's values written out, and indexes of them for agents."
canonical_url: "http://localhost:3000/getting-started/agents/markdown"
---
# Markdown and llms.txt

> Every page of these docs as Markdown, with its examples, options and the theme's values written out, and indexes of them for agents.

These docs are written for agents as much as for people: an agent that builds a page reads the blocks' pages, copies their MDC and sets their options with the values of the site's theme. A documentation site built on this layer (with [Docus](https://docus.dev)) serves every page as Markdown, and the components of the pages are written out in it: the examples as their MDC, the options and slots as lists, with the values of the site's theme, and the site's notes on its theme.

## A page as Markdown

Each page has a Markdown twin:

- `/raw/<path>.md`, e.g. `/raw/components/cards-and-grids/card.md`;
- the page's address with `.md`: `/components/cards-and-grids/card.md`;
- the page's address with an `Accept: text/markdown` header (and for the known agents' user agents).

```bash
curl https://docs.example.org/components/cards-and-grids/card.md
```

The Markdown opens with front matter (`title`, `description`, `canonical_url`), then the page:

- an example (`::component-example`) is its MDC code block;
- `:component-options` is a list of the block's options: their values (the default in bold), marked "the theme's values" for its look options, and their description;
- `:component-slots` is a list of its slots;
- `::component-looks` gives the values of a look option in the site's theme, and the example with one of them;
- `:theme-notes` is the site's notes on its theme of the block;
- `:theme-looks` lists every block's look options and their values.

## Indexes

<table>
<thead>
  <tr>
    <th>
      Address
    </th>
    
    <th>
      What it is
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        /sitemap.md
      </code>
    </td>
    
    <td>
      Every page, by section, linking to their Markdown.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /llms.txt
      </code>
    </td>
    
    <td>
      The <a href="https://llmstxt.org" rel="nofollow">
        llms.txt
      </a>
      
       index of the pages, with the site's address set (<code>
        site.url
      </code>
      
      , e.g. from <code>
        SITE_URL
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /llms-full.txt
      </code>
    </td>
    
    <td>
      Every page's Markdown in one document (with the site's address set).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /openapi.json
      </code>
    </td>
    
    <td>
      The routes the site serves to agents.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /.well-known/api-catalog
      </code>
    </td>
    
    <td>
      The discovery links (<a href="https://www.rfc-editor.org/rfc/rfc9727" rel="nofollow">
        RFC 9727
      </a>
      
      ).
    </td>
  </tr>
</tbody>
</table>

## Building a page

What an agent needs, in order:

1. [MDC syntax](http://localhost:3000/writing-pages/mdc-syntax) and the [rules](http://localhost:3000/writing-pages/rules) a page must follow so that Studio can edit and save it.
2. [Page structure](http://localhost:3000/writing-pages/page-structure): the front matter, a header, then sections.
3. The blocks' pages (Components), for their slots, options and the values of the site's theme, and [Composing blocks](http://localhost:3000/writing-pages/composing-blocks) for the usual combinations.
4. The site's own pages: its theme, its own blocks, how its pages are built.


## Sitemap

See the full [sitemap](http://localhost:3000/sitemap.md) for all pages.