Markdown & llms.txt
vitepress-openapi can generate plain Markdown from your OpenAPI spec at build time. Use it for:
- LLMs and AI agents: a
.mdfile next to each operation page (e.g./operations/getPet.mdfor/operations/getPet.html), plusllms.txtandllms-full.txt. This is the recommended setup for sites: see Next to your pages. - Static, searchable pages: plain
.mdfiles in your repo that VitePress renders like any other page, indexed by local search or Algolia, with almost no JavaScript. See CLI.
Each operation includes its endpoint, description, servers, authorization, parameters, request body and responses (schemas and examples), and code samples (cURL by default).
Tradeoff
Generated pages are static Markdown: there is no interactive playground, no schema/JSON toggles and no theme customizations. If you need those, use OAOperation or OASpec pages instead (or in addition).
Demo
This site writes the Markdown of every example operation page next to its HTML, from its example spec:
- Get all artists (page) and getAllArtists.md (Markdown).
- one-page.md: the whole spec, for the one-page example.
- introduction.md: the API overview, for the introduction example.
- Artists.md: every operation of a tag, for the Artists tag page.
- response-statuses.md: a page rendering its own spec, for the Response Statuses test page.
- llms.txt and llms-full.txt.
Next to your pages
If your site has operation pages, generateLlmsFiles writes {route}.md next to each built page, and llmsDevServer serves the same files in dev. Share the options between both:
// .vitepress/config.mts
import { defineConfig } from 'vitepress'
import { generateLlmsFiles, llmsDevServer } from 'vitepress-openapi'
import spec from '../public/openapi.json' with { type: 'json' }
const llms = {
spec,
operationRoute: 'operations/{operationId}', // route of your [operationId].md pages
specRoutes: ['reference'], // optional: pages rendering the whole spec (OASpec)
introductionRoute: 'introduction', // optional: API overview page
tagRoute: 'tags/{tag}', // optional: route of your [tag].md pages
openapiUrl: '/openapi.json',
}
export default defineConfig({
async buildEnd(siteConfig) {
await generateLlmsFiles(siteConfig, llms)
},
vite: {
plugins: [llmsDevServer(llms)],
},
})| Option | Description |
|---|---|
spec | OpenAPI document (object or JSON/YAML string). Or use specPath / specUrl. |
operationRoute | Route of the operation pages, relative to the site root, with an {operationId} placeholder. |
specRoutes | Routes of pages rendering the whole spec: they get every operation in one file. |
introductionRoute | Route of an overview page: title, version, description, servers, authentication and operations by tag, linked to their pages. |
tagRoute | Route of the tag pages, with a {tag} placeholder. Each gets the tag description and all its operations. |
tagParam | Value of {tag} for a tag name. Defaults to the name as is, like usePaths().getTags() in a [tag].paths.js file. Set it if your paths file slugifies tags. |
extension | md (default) or txt. |
llmsTxt | Write llms.txt and llms-full.txt at the site root (default true). |
openapiUrl | URL of the OpenAPI document, linked from every file. |
codeSamples | Languages of the code samples (default ['curl']), or false. baseUrl sets the base URL used in them. |
maxSize | Maximum size in bytes of files with many operations: whole-spec pages, tag pages and llms-full.txt (default 5 MB, 5 * 1024 * 1024). Above it, a summary is written instead, and a warning is logged. false disables it. |
Files are only written for routes that exist as pages, and links (in llms.txt and between operations) include the site base. llms.txt links the overview first and each tag page at the top of its section. The files have no frontmatter: they are served as they are.
Each page with its own spec
Pages that render their own spec (e.g. <OASpec :spec="..." /> with the spec in route params) are covered by resolvePage. It is called for every built page with its route and dynamic route params, and returns what the page renders, or undefined to skip it:
const llms = [
{ spec, operationRoute: 'operations/{operationId}' },
{
title: 'Examples', // section heading in llms.txt
resolvePage: ({ route, params }) => route.startsWith('examples/')
? { specUrl: params.specUrl }
: undefined,
},
]| Returned field | Description |
|---|---|
spec / specPath / specUrl | The page's spec. Defaults to the entry's spec. URLs are fetched once; a failed fetch skips the page with a warning. |
mode | 'spec' (default, every operation), 'operation', 'introduction' or 'tag'. |
operationId / tag | For the 'operation' and 'tag' modes. |
maxSize | Overrides the entry's maxSize for this page. |
Operation links inside these files are plain text, since the page's spec has no operation pages. Pass an array of options objects, each with its own spec, to generateLlmsFiles and llmsDevServer:
- One
llms.txtand onellms-full.txtare written.extensionandllmsTxtare read from the first entry. llms.txtstarts with the first entry that hasoperationRoute. Other entries add a## Section: their operations, or the pages ofresolvePage(titled with each spec'sinfo.title).llms-full.txtonly contains the specs of entries withoperationRoute. Pages ofresolvePageare linked fromllms.txt, not copied, to keep it small.maxSizeapplies to each file, and to the part ofllms-full.txtof each entry: a whole-spec or tag file over it becomes a summary (the overview, then one line per operation, linked to its page when there is one), with a note linking the spec. Very large specs (e.g. Stripe's) end up as summaries with the default limit.
In dev, the requested route is matched to a page and its params from VitePress' resolved dynamic routes.
vitepress-plugin-llms
vitepress-plugin-llms copies the Markdown source of each page, which for operation pages is just <OAOperation />. You can use both: buildEnd runs after Vite plugins, so these files overwrite theirs on operation routes. In dev, register llmsDevServer before llmstxt() in vite.plugins. To keep its llms.txt instead, set llmsTxt: false.
CLI
npx vitepress-openapi generate docs/public/openapi.json --out docs/api --link-prefix /api/<spec> can be a local JSON/YAML file or a URL.
| Option | Description |
|---|---|
-o, --out <dir> | Output directory (required). |
--group-by <mode> | operation (default): one file per operation. tag: one file per tag. |
--link-prefix <prefix> | Prefix of the links in llms.txt (default /). Can be an absolute URL. |
--openapi-url <url> | URL of the OpenAPI document, linked from every page. |
--code-samples <langs> | Comma-separated languages: curl, javascript, php, python (default curl). |
--no-code-samples | Do not include code samples. |
--base-url <url> | Base URL used in code samples (default: the first server). |
--no-llms | Do not generate llms.txt and llms-full.txt. |
--no-frontmatter | Do not add VitePress frontmatter. |
--clean | Remove the output directory before writing. |
The output looks like this:
/docs/api
├── index.md # API info and links to every operation, grouped by tag
├── getPet.md # one file per operation (or per tag with --group-by tag)
├── createPet.md
├── llms.txt # index for AI agents (https://llmstxt.org)
└── llms-full.txt # every operation in a single fileOperation ids are sanitized to build file names (e.g. pets/get becomes pets-get.md). Operations without operationId use the same fallback as the rest of the library ({method}-{path}).
From the VitePress config
generateMarkdown does the same as the CLI, so you can run it every time VitePress starts or builds:
// .vitepress/config.mts
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vitepress'
import { generateMarkdown } from 'vitepress-openapi'
await generateMarkdown({
specPath: fileURLToPath(new URL('../public/openapi.json', import.meta.url)),
outDir: fileURLToPath(new URL('../api', import.meta.url)),
clean: true,
llms: false,
})
export default defineConfig({
// ...
})Use spec (object or JSON/YAML string), specPath or specUrl to load the document. The remaining options match the CLI ones in camelCase (groupBy, linkPrefix, openapiUrl, codeSamples, baseUrl, llms, frontmatter, clean).
To keep the files in memory (e.g. for a custom plugin), use generateMarkdownFiles(spec, options), which returns { path, content }[] without touching the file system. To render a single operation, use operationToMarkdown(openapi, operationId, options), where openapi is the instance returned by useOpenapi({ spec }).
Links in descriptions that use the operation links syntax ([](/operations/getPet)) point to the generated files.
Grouping
--group-by operation(default): one page per operation, titled with the operation summary.--group-by tag: one page per tag with all its operations. Operations with several tags are included in each of them.
Both modes generate index.md with links grouped by tag.
llms.txt for AI agents
For a site, prefer Next to your pages. With the CLI, note that VitePress turns .md files into HTML pages and does not serve .txt files from your docs folder. To expose the raw files to AI agents, generate them into public without frontmatter, so they are served as they are:
npx vitepress-openapi generate docs/public/openapi.json \
--out docs/public/api \
--no-frontmatter \
--link-prefix https://example.com/api/ \
--openapi-url https://example.com/openapi.jsonAgents can then read https://example.com/api/llms.txt, follow its links to each operation .md, or load everything at once from llms-full.txt. You can run the generator twice (once into docs/api for pages, once into docs/public/api for agents) to get both.
INFO
With frontmatter enabled, the content is wrapped in a ::: v-pre container, so double curly braces in your descriptions are not interpreted by Vue.