Headless docs with a custom frontend

Build a headless documentation frontend with Astro while using Mintlify for content management, AI-powered search, and assistant features.

Mintlify’s headless mode lets you build your own frontend with Astro while using Mintlify to manage content, search, and AI features. Use this when you need full control over design, layout, or behavior — for example, to match an existing design system or embed docs into a larger site.

The @mintlify/astro integration reads your docs.json config and MDX content at build time and processes everything into a format Astro can render.

Show Feature availability for headless projects

Feature	Availability	Notes
Mintlify components	Included	Use components like <Card>, <Steps>, and <Tabs> in your MDX files without importing them.
Content processing	Included	The @mintlify/astro integration reads your docs.json and MDX files and processes them at build time.
Search	Included	The SearchBar component connects to Mintlify’s search API using your project subdomain.
AI assistant	Included	The Assistant component provides an AI chat interface powered by your content. Available on Pro and Enterprise plans.
Layouts and styling	Custom build	Header, footer, sidebar, table of contents, page templates, and all CSS. The starter template includes examples built with Tailwind CSS.
Routing and navigation	Custom build	A catch-all Astro route renders each page. Use resolvePageData() and unwrapNav() from @mintlify/astro/helpers to resolve navigation state from docs.json.
Deployment and hosting	Custom build	Deploy your Astro site to any hosting provider.
SEO	You build	Meta tags, Open Graph tags, sitemap, and robots.txt are your responsibility to generate.
Third-party integrations	Custom build	Add integrations directly to your Astro layout. Tools configured in docs.json for hosted projects do not apply in headless.
llms.txt, llms-full.txt, and skill.md	Custom build	For headless projects, you must generate and serve these files.
Dashboard analytics	Custom build	If you use the Assistant component, assistant usage analytics are available in your dashboard. For page traffic, add your own analytics provider to your Astro layout.
Web editor	Not available	Requires Mintlify’s hosted rendering environment.
Authentication and password protection	Not available	Only available for sites hosted on a Mintlify subdomain or custom domain pointed at Mintlify.
API playground	Not available	Only available for sites hosted on the Mintlify platform.
User feedback	Not available	The page feedback feature is part of Mintlify’s hosted rendering layer.
Preview deployments	Not available	Use your hosting provider’s preview environment.
PDF export	Not available	Not available for headless projects.

Prerequisites

• A Mintlify account
• A GitHub account
• Node.js v20.17.0 or later (LTS recommended)
• Familiarity with Astro

Set up your project

1. Create a repository from the starter template

   Go to the mintlify-astro-starter repository on GitHub, click Use this template to create a new repository, and clone it locally.

2. Sign up for Mintlify

   If you don’t have an account, sign up at dashboard.mintlify.com/signup.

3. Install the GitHub app

   On the Git settings page, install the Mintlify GitHub app. If already installed, uninstall and reinstall it to connect your new repository.

4. Connect your repository

   1. On the Git settings page, select your starter template repository.
   2. Enable Set up as monorepo and enter /docs as the docs directory path.
   3. Click Save changes.

   
5. Configure environment variables

   Create a .env file at the project root:

   .env

   PUBLIC_MINTLIFY_SUBDOMAIN=your-subdomain
   PUBLIC_MINTLIFY_ASSISTANT_KEY=your-assistant-api-key
   

   Your subdomain is the part of your dashboard URL after the organization name (e.g., domain-name from https://dashboard.mintlify.com/org-name/domain-name).

   On Pro or Enterprise plans, generate an assistant API key (starts with mint_dsc_) on the API keys page.

6. Start the dev server

   cd path/to/your-repository
   npm install
   npm run dev
   

   Your site runs at http://localhost:4321.

How it works

The integration connects the Astro build system, your docs/ content, and the Mintlify packages that process and render it.

Astro configuration

Configure the mintlify() integration in astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import mdx from '@astrojs/mdx';
import { mintlify } from '@mintlify/astro';

export default defineConfig({
  integrations: [mintlify({ docsDir: './docs' }), react(), mdx()],
});

At build time, the integration processes your docs.json and MDX files from docsDir into .mintlify/docs/, where Astro’s content collections pick them up.

Content structure

Structure your docs/ directory the same way as any Mintlify project:

docs/
├── docs.json          # Navigation and site configuration
├── index.mdx          # MDX pages for content
├── quickstart.mdx
└── guides/            # Directories for organizing pages
    ├── setup.mdx
    └── troubleshooting.mdx

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:

• 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, sidebar, table of contents, and styles built with Tailwind CSS — replace any of these with your own.

File	Purpose
src/layouts/Layout.astro	Root HTML layout
src/pages/[...slug].astro	Page template and data loading
src/components/Header.astro	Site header
src/components/Sidebar/	Sidebar navigation
src/components/TableOfContents.tsx	On-page table of contents
src/styles/	Global styles, typography, and color scheme

Search and assistant

The assistant is available on Pro and Enterprise plans.

The starter template includes search and assistant components that connect to Mintlify’s APIs using your environment variables:

• Search — SearchBar component in src/components/SearchBar.tsx
• Assistant — Assistant component in src/components/Assistant/ for AI-powered chat

Both require PUBLIC_MINTLIFY_SUBDOMAIN and PUBLIC_MINTLIFY_ASSISTANT_KEY.

Next steps

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 Astro site to your preferred hosting provider.