Skip to main content
Mintlify’s headless mode lets you control how your documentation looks and behaves while using Mintlify to manage your content. Instead of using Mintlify’s hosted frontend, you can build your own custom frontend with Astro and render your MDX content and 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

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

  1. On the Git settings page, select the repository you created from the starter template.
  2. Enable the Set up as monorepo toggle.
  3. Enter /docs as the path to the directory containing your docs.json file.
  4. Click Save changes.
5

Configure environment variables

Clone your new repository locally and create a .env file at the project root with your Mintlify credentials:
.env
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 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_.
Don’t add the PUBLIC_ prefix to MINTLIFY_ASSISTANT_KEY. Astro bundles PUBLIC_ variables into client code. Anyone who copies the key from your site can use your assistant credits and read protected pages in your project.
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 the docs/ directory, and the Mintlify packages that process and render that content.

Astro configuration

Configure the mintlify() integration in astro.config.mjs with the path to your docs directory:
astro.config.mjs
At build time, the integration reads your 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 the docs/ directory, structured the same way as any other Mintlify project:
MDX files use standard Mintlify frontmatter and can use Mintlify components without importing them.

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 SearchBar component in src/components/SearchBar.tsx sends queries to the /api/search route.
  • Assistant: The Assistant component in src/components/Assistant/ provides an AI chat interface that answers questions using your documentation content. It sends messages to the /api/assistant route, which streams the response back.
Both routes live in 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:
Set 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:
  1. Replace the starter content in docs/ with your own MDX files and docs.json configuration.
  2. Customize layouts and styles to match your design system.
  3. Deploy your site to your hosting provider.