Mintlify

Promptfree, for everyone, and the only version there is

Copy the prompt for Claude CodeCopy the prompt for CodexCopy the prompt for Cursor

Copy

Build me documentation that replaces Mintlify: Markdown in, a fast designed site out, with a request playground and search that works.

STACK
- Astro with Starlight as the base, or Astro from scratch if the design must be entirely yours. Do not build a static site generator
- Pagefind for search — it builds an index at build time and searches entirely in the browser, with no server and no per-query cost
- SQLite through better-sqlite3 only for the analytics, if you want them
- Caddy in front

THE CONTENT
- MDX or Markdown files in the repository, alongside the code they document. Documentation that lives elsewhere goes stale, and this is the whole argument for a static generator
- Front matter: title, description, sidebar order, tags, and a version
- Components available inside the content: callouts, tabs, accordions, code groups, parameter tables, and a request playground
- A sidebar generated from the directory structure with explicit ordering where it matters
- Every page has a permanent URL. Moving a page writes a redirect rather than breaking every link anyone has shared

THE API PLAYGROUND, WHICH IS WHAT THE FEE BUYS
- Generated from an OpenAPI document: every endpoint gets a page with its parameters, its schemas, its responses and examples, without anybody writing them twice
- A form built from the schema, with types, required fields, enums and defaults respected
- Authentication handled: the reader enters a token once, it is kept in their browser's session storage and never sent anywhere but the API being called
- Send the request from the browser where CORS allows, and through a small proxy on your own server where it does not. That proxy must refuse private address ranges and be rate-limited, or it becomes a request forgery machine
- The response shown with status, headers, timing and a formatted body
- A curl command for every request, and code samples in several languages generated from the same source rather than written by hand
- If the OpenAPI document is in the repository, the docs cannot drift from the API. That is the point

SEARCH
- Pagefind indexes at build time and runs in the browser. No search server, no query cost, works offline, and it is fast on thousands of pages
- Index the headings and the body separately so a heading match ranks higher
- Filters by section and by version
- Keyboard shortcut to open it, arrow keys to move, Enter to go. This is used constantly and every extra click is felt
- Record what people searched for, and especially what returned nothing — an empty search result is a request for a page, and it is the single most useful piece of documentation analytics there is

VERSIONS AND LANGUAGES
- Versioned documentation as directories, with a switcher, and a canonical URL pointing at the current version so search engines do not index four copies
- A banner on an old version saying so, with a link to the current one
- Translations only if you have somebody to maintain them; a half-translated documentation site is worse than an untranslated one

DESIGN
- Fast: server-rendered or static HTML, no framework at runtime, under 100KB for a page
- A self-hosted variable font as WOFF2, never one from a third-party CDN
- Dark and light, both legible, with every colour pair measured against WCAG AA rather than chosen by eye
- Code blocks with syntax highlighting done at build time, a copy button, filename labels, and line highlighting
- A table of contents on the right that tracks the reading position
- Works at 320px with nothing hidden and nothing clipped

WHAT DOCUMENTATION SITES GET WRONG
- Open Graph tags and a generated share image per page, so a link posted in chat is legible
- JSON-LD: TechArticle and BreadcrumbList
- A sitemap, canonical URLs, and an llms.txt
- An edit-this-page link straight to the file in the repository, which is how a typo gets fixed by the person who found it
- A was-this-helpful control, counted per page, with an optional free-text box — and somebody actually reading the answers
- Every code sample tested, or at least compiled, in CI. A documentation site full of examples that no longer run is worse than no examples

ANALYTICS
- First-party, no third party: page, referrer, a coarse device bucket, and a salted visitor hash. No cookie
- Failed searches, helpful votes, and the pages nobody reaches
- Or nothing at all, which is a legitimate choice

OPERATIONS
- Built in CI on every merge and deployed as static files, with the playground proxy as the only server component
- .env for the proxy: BASE_URL, ALLOWED_API_HOSTS, RATE_LIMIT
- Cache headers: hashed assets immutable, HTML short
- A link checker in CI, internal and external, so a dead link is a failing build

WHAT MATTERS MOST
The OpenAPI-generated playground and search. Build generation from the specification first — that is the difference between documentation and a website — and record the searches that find nothing, because that list is your writing backlog.

Give me the repository, the OpenAPI generator, the playground proxy, the CI workflow, and a README with deploy steps behind Caddy.