Markdown, MDX, And Text Exports

Authoring Formats

Relevate supports both .mdx and .md source pages.

Use .mdx when you want Relevate components such as Card, Steps, CodeGroup, or ResponseField.
Use .md when the page is plain Markdown and should stay portable.
Link between pages with route paths or source-style links such as guide.md and guide.mdx.

Both .md and .mdx pages compile into normal docs routes and can live together in the same navigation group.

Source Layout

docs

docs.json

index.mdx

quickstart.md

guides

install.md

configure.mdx

Add pages to navigation without the extension:

{
  "navigation": {
    "tabs": [
      {
        "id": "docs",
        "label": "Docs",
        "content": [
          {
            "title": "Guides",
            "pages": ["quickstart", "guides/install", "guides/configure"]
          }
        ]
      }
    ]
  }
}

Linking Between Pages

Relevate rewrites internal Markdown and MDX file links so authors can use natural source links.

Read [Install](./install.md) before [Configuration](./configure.mdx).

The compiled page links to the matching public routes instead of exposing source file extensions.

Use source-style links when you want docs to remain readable in GitHub. Use route links such as /guides/install when you want the public URL to be explicit.

Markdown Responses

Every visible, indexable page can be requested as clean Markdown.

Explicit .md URL
```
curl https://docs.example.com/guides/install.md
```
Thanks. We will use this to improve the snippet.
Accept header
```
curl -H "Accept: text/markdown" https://docs.example.com/guides/install
```
Thanks. We will use this to improve the snippet.
Plain text preference
```
curl -H "Accept: text/plain" https://docs.example.com/guides/install
```
Thanks. We will use this to improve the snippet.

Relevate returns text/markdown; charset=utf-8 for Markdown responses.

What Gets Included

Markdown responses are built from your published page content in a reader-friendly text format.

They include:

Page title, URL, locale, and canonical path metadata
Section headings and anchor IDs
The page body in Markdown-friendly form
Optional agent feedback instructions when enabled

They exclude:

Hidden pages
noindex pages
Navigation chrome, footer HTML, and theme layout

Agent Feedback Instructions

Relevate can append an <AgentInstructions> block to Markdown responses. This block tells compatible agents how to submit precise feedback when they find incorrect, outdated, or confusing docs.

<AgentInstructions>

## Submitting Feedback

POST https://docs.example.com/_relevate/agent/feedback

{
  "path": "guides/install",
  "feedback": "Description of the issue"
}

</AgentInstructions>

The feedback block is only appended when agent feedback is enabled for the docs site.

Relevate also serves a docs skill file at /skill.md.

By default, Relevate generates it from your site name, description, languages, and key pages. To fully control it, add skill.md or SKILL.md at the docs source root.

docs

docs.json

skill.md

index.mdx

The generated or custom skill is served as text/markdown; charset=utf-8.

Best Practices

Prefer .mdx for pages that teach with Relevate components.
Prefer .md for portable specs, policies, and simple runbooks.
Keep one main task per page so Markdown exports are useful to both readers and agents.
Add descriptive frontmatter to every page so text exports and assistant records have strong context.