docs.json configuration however you want.
This headless approach is useful when you need full control over your documentation’s design, layout, or behavior. For example, use it to match an existing design system or embed documentation into a larger site. You still get Mintlify’s publishing, search, MDX components, and AI features.
The @mintlify/astro integration reads your docs.json config and MDX content at build time, then processes everything into a format that Astro can render. Build your own layouts, components, and styles on top of it.
This guide walks you through setting up a headless Mintlify project with the starter template and getting it running locally.
Prerequisites
- A Mintlify account
- A GitHub account
- Node.js v20.17.0 or later (LTS versions recommended)
- Familiarity with Astro
- A hosting provider that runs server-side code, such as Node.js, for search and the assistant
Set up your project
1
Create a repository from the starter template
Navigate to the mintlify-astro-starter repository on GitHub and click Use this template to create a new repository on your account.Clone the repository to your local machine.
2
Sign up for Mintlify
If you don’t have a Mintlify account, sign up at app.mintlify.com/signup.
3
Install the GitHub App
On the Git settings page of your Mintlify dashboard, install the Mintlify GitHub App. If you already have the app installed, uninstall it and reinstall it so that you are ready to connect your new repository.
4
Connect your repository
- On the Git settings page, select the repository you created from the starter template.
- Enable the Set up as monorepo toggle.
- Enter
/docsas the path to the directory containing yourdocs.jsonfile. - Click Save changes.
5
Configure environment variables
Clone your new repository locally and create a Your subdomain is the domain name of your project. It is the part of your dashboard URL after the organization name. For example, if your dashboard URL is
.env file at the project root with your Mintlify credentials:.env
https://app.mintlify.com/org-name/domain-name, your subdomain is domain-name.Generate an assistant API key on the API keys page of your dashboard. The assistant API key starts with mint_dsc_.6
Start the dev server
Install dependencies and start the local development server in your cloned repository:Your site now runs locally at
http://localhost:4321.How it works
The integration connects three parts: the Astro build system, your content in thedocs/ directory, and the Mintlify packages that process and render that content.
Astro configuration
Configure themintlify() integration in astro.config.mjs with the path to your docs directory:
astro.config.mjs
docs.json and MDX files from the docsDir path and processes them into .mintlify/docs/, where Astro’s content collections pick them up.
Astro prerenders your pages to static HTML. The Node.js adapter serves them and runs the server routes for search and the assistant. The env schema declares MINTLIFY_ASSISTANT_KEY as a server secret, so the server reads it at runtime and Astro never writes it into the build output.
Content structure
Your documentation content lives in thedocs/ directory, structured the same way as any other Mintlify project:
Routing and navigation
A catch-all route renders each MDX page. The@mintlify/astro/helpers package provides functions to resolve navigation state from your docs.json.
resolvePageData(): Returns tabs, sidebar navigation, footer links, and anchors for a given page path.unwrapNav(): Flattens the navigation tree into a list for sidebar rendering.
Layouts and styling
You control the full presentation layer. The starter template includes layouts, a sidebar, table of contents, and styles built with Tailwind CSS, but you can replace any of these with your own. Key files to customize:Connect search and assistant
The starter template includes search and assistant components that connect to Mintlify’s APIs through server routes in your site. The browser never calls Mintlify’s APIs directly, so your assistant API key stays on your server.- Search: The
SearchBarcomponent insrc/components/SearchBar.tsxsends queries to the/api/searchroute. - Assistant: The
Assistantcomponent insrc/components/Assistant/provides an AI chat interface that answers questions using your documentation content. It sends messages to the/api/assistantroute, which streams the response back.
src/pages/api/ and need the PUBLIC_MINTLIFY_SUBDOMAIN and MINTLIFY_ASSISTANT_KEY environment variables. Each route adds your API key to the request and forwards it to Mintlify. The routes set the request options, such as search filters, so visitors can’t change them.
Anyone who can open your site can call these routes, and each call uses your assistant credits.
Deploy your site
The starter template uses the Node.js adapter, so you can deploy it to any host that runs a Node.js server. Build the site and start the server:PUBLIC_MINTLIFY_SUBDOMAIN before you build. Set MINTLIFY_ASSISTANT_KEY in your host’s environment variables. The production server doesn’t read your .env file.
To deploy to a platform such as Vercel, Netlify, or Cloudflare, replace the Node.js adapter in astro.config.mjs with that platform’s Astro adapter. Search and the assistant don’t work without an adapter.
Next steps
After setting up your project:- Replace the starter content in
docs/with your own MDX files anddocs.jsonconfiguration. - Customize layouts and styles to match your design system.
- Deploy your site to your hosting provider.