mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
194421572c
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
128 lines
4.9 KiB
Plaintext
128 lines
4.9 KiB
Plaintext
---
|
|
title: "Markdown export"
|
|
description: "Export clean Markdown versions of your documentation pages for AI tools, LLM integrations, and automated content processing workflows."
|
|
keywords: ["markdown", "token efficiency", "AI processing"]
|
|
---
|
|
|
|
import { PreviewButton } from "/snippets/previewbutton.jsx"
|
|
|
|
Markdown provides structured text that AI tools can process more efficiently than HTML, which results in better response accuracy, faster processing times, and lower token usage.
|
|
|
|
Mintlify automatically generates Markdown versions of pages optimized for AI tools and external integrations.
|
|
|
|
## .md URL extension
|
|
|
|
Add `.md` to any page's URL to view a Markdown version.
|
|
|
|
<PreviewButton href="https://mintlify.com/docs/ai/markdown-export.md">Open this page as Markdown</PreviewButton>
|
|
|
|
## Accept header
|
|
|
|
Send a request with `Accept: text/markdown` or `Accept: text/plain` to any page URL to receive the Markdown version instead of HTML. This is useful for AI tools and integrations that programmatically fetch documentation content.
|
|
|
|
```bash
|
|
curl -L -H "Accept: text/markdown" https://mintlify.com/docs/ai/markdown-export
|
|
```
|
|
|
|
## Missing pages
|
|
|
|
If you request a page that doesn't exist as Markdown, Mintlify returns a 404 status with a Markdown body that helps AI tools recover. The response links to your documentation index (`llms.txt`), your full documentation file (`llms-full.txt`), and up to three related pages based on the requested path.
|
|
|
|
```md Example Markdown 404 response
|
|
> ## Documentation Index
|
|
> Fetch the documentation index at: https://example.com/docs/llms.txt
|
|
> Use this file to discover all available pages before exploring further.
|
|
> For broader context, fetch the full documentation at: https://example.com/docs/llms-full.txt (large file).
|
|
|
|
# Page Not Found
|
|
|
|
The requested page could not be found.
|
|
|
|
## Related topics
|
|
|
|
- [Getting started](https://example.com/docs/getting-started.md)
|
|
```
|
|
|
|
Related page suggestions come from the same search that powers your site's [404 page](/customize/custom-404-page). Sites that use [authentication](/deploy/authentication-setup) omit suggestions and return only the documentation links.
|
|
|
|
## Audience-specific content
|
|
|
|
Use the [visibility](/components/visibility) component to customize content for human and AI audiences.
|
|
|
|
Content wrapped in `<Visibility for="humans">` appears on the web page, but not in Markdown output. Content wrapped in `<Visibility for="agents">` appears in Markdown output, but not on the web page.
|
|
|
|
```mdx
|
|
<Visibility for="humans">
|
|
Click the **Get started** button in the top-right corner to create your account.
|
|
</Visibility>
|
|
|
|
<Visibility for="agents">
|
|
To create an account, call `POST /v1/accounts` with a valid email address.
|
|
</Visibility>
|
|
```
|
|
|
|
## API reference pages
|
|
|
|
By default, Markdown exports of API reference pages include the full OpenAPI or AsyncAPI specification so AI tools have complete context about each endpoint.
|
|
|
|
If you prefer to omit the spec from Markdown output, set `markdown.schema` to `false` in your `docs.json`:
|
|
|
|
```json
|
|
"markdown": {
|
|
"schema": false
|
|
}
|
|
```
|
|
|
|
## Custom agent instructions
|
|
|
|
To append your own guidance to the Markdown that Mintlify serves to AI agents, set `markdown.instructions` in your `docs.json`. Use it for site-wide directions like citing an API version, preferring a specific SDK, or following your terminology.
|
|
|
|
Provide a single string:
|
|
|
|
```json Example agent instructions string
|
|
"markdown": {
|
|
"instructions": "Always cite the API version. Prefer the TypeScript SDK in examples."
|
|
}
|
|
```
|
|
|
|
Or an array of strings, which Mintlify joins with line breaks:
|
|
|
|
```json Example agent instructions array
|
|
"markdown": {
|
|
"instructions": [
|
|
"Always cite the API version.",
|
|
"Prefer the TypeScript SDK in examples."
|
|
]
|
|
}
|
|
```
|
|
|
|
Mintlify renders your instructions as an `Agent Instructions` block in the Markdown output:
|
|
|
|
```md Example rendered agent instructions
|
|
> ## Agent Instructions
|
|
> Always cite the API version.
|
|
> Prefer the TypeScript SDK in examples.
|
|
```
|
|
|
|
The block appears in:
|
|
|
|
- The Markdown export of every page, including API reference pages.
|
|
- Your [`llms.txt`](/ai/llmstxt) file, after the site title and description.
|
|
- Your `llms-full.txt` file.
|
|
|
|
These instructions apply to every page. To tailor content for a single page or audience, use the [visibility](/components/visibility) component instead.
|
|
|
|
## Authentication
|
|
|
|
Markdown export respects the same authentication rules as the HTML version of each page.
|
|
|
|
| Authentication mode | Behavior |
|
|
|-----------|----------|
|
|
| No authentication | All `.md` URLs are publicly accessible. |
|
|
| Partial authentication | `.md` URLs for public pages are publicly accessible. `.md` URLs for protected pages require authentication and respect user group restrictions. |
|
|
| Full authentication | All `.md` URLs require authentication and respect user group restrictions. |
|
|
|
|
## Keyboard shortcut
|
|
|
|
Press <kbd>Cmd</kbd> + <kbd>C</kbd> (<kbd>Ctrl</kbd> + <kbd>C</kbd> on Windows) to copy a page as Markdown to your clipboard.
|