Quickstart

Start building awesome documentation in minutes

Get started in three steps

Get your documentation site running locally and make your first customization.

Step 1: Set up your local environment

Clone your docs locally

During the onboarding process, you created a GitHub repository with your docs content if you didn’t already have one. You can find a link to this repository in your dashboard.

To clone the repository locally so that you can make and preview changes to your docs, follow the Cloning a repository guide in the GitHub docs.

Start the preview server

1. Install the Mintlify CLI: npm i -g mint
2. Navigate to your docs directory and run: mint dev
3. Open http://localhost:3000 to see your docs live!

Your preview updates automatically as you edit files.

Step 2: Deploy your changes

Install our GitHub app

Install the Mintlify GitHub app from your dashboard.

Our GitHub app automatically deploys your changes to your docs site, so you don’t need to manage deployments yourself.

Update your site name and colors

For a first change, let’s update the name and colors of your docs site.

1. Open docs.json in your editor.
2. Change the "name" field to your project name.
3. Update the "colors" to match your brand.
4. Save and see your changes instantly at http://localhost:3000.

Try changing the primary color to see an immediate difference!

Step 3: Go live

Publish your docs

1. Commit and push your changes.
2. Your docs will update and be live in moments!

Next steps

Now that you have your docs running, explore these key features:

Write Content

Learn MDX syntax and start writing your documentation.

Customize style

Make your docs match your brand perfectly.

Add code examples

Include syntax-highlighted code blocks.

API documentation

Auto-generate API docs from OpenAPI specs.

Need help? See our full documentation or join our community.

Titles

Best used for section headers.

## Titles

Subtitles

Best used for subsection headers.

### Subtitles

Each title and subtitle creates an anchor and also shows up on the table of contents on the right.

Text formatting

We support most markdown formatting. Simply add **, _, or ~ around text to format it.

Style	How to write it	Result
Bold	**bold**	bold
Italic	_italic_	italic
Strikethrough	~strikethrough~	strikethrough

You can combine these. For example, write **_bold and italic_** to get bold and italic text.

You need to use HTML to write superscript and subscript text. That is, add <sup> or <sub> around your text.

Text Size	How to write it	Result
Superscript	<sup>superscript</sup>	superscript
Subscript	<sub>subscript</sub>	subscript

Linking to pages

You can add a link by wrapping text in [](). You would write [link to google](https://google.com) to link to google.

Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, [link to text](/writing-content/text) links to the page “Text” in our components section.

Relative links like [link to text](../text) will open slower because we cannot optimize them as easily.

Blockquotes

Singleline

To create a blockquote, add a > in front of a paragraph.

Dorothy followed her through many of the beautiful rooms in her castle.

> Dorothy followed her through many of the beautiful rooms in her castle.

Multiline

Dorothy followed her through many of the beautiful rooms in her castle.

The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

LaTeX

Mintlify supports LaTeX through the Latex component.

8 x (vk x H1 - H2) = (0,1)

<Latex>8 x (vk x H1 - H2) = (0,1)</Latex>

The navigation menu is the list of links on every website.

You will likely update docs.json every time you add a new page. Pages do not show up automatically.

Navigation syntax

Our navigation syntax is recursive which means you can make nested navigation groups. You don’t need to include .mdx in page names.

Regular Navigation

"navigation": {
  "tabs": [
    {
      "tab": "Docs",
      "groups": [
        {
          "group": "Getting Started",
          "pages": ["quickstart"]
        }
      ]
    }
  ]
}

Folders

Simply put your MDX files in folders and update the paths in docs.json.

For example, to have a page at https://yoursite.com/your-folder/your-page you would make a folder called your-folder containing an MDX file called your-page.mdx.

You cannot use api for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level api folder for internal server calls. A folder name such as api-reference would be accepted.

Navigation With Folder

"navigation": {
  "tabs": [
    {
      "tab": "Docs",
      "groups": [
        {
          "group": "Group Name",
          "pages": ["your-folder/your-page"]
        }
      ]
    }
  ]
}

Hidden pages

MDX files not included in docs.json will not show up in the sidebar but are accessible through the search bar and by linking directly to them.

Endpoint

GET /api/items

Parameters

Parameter	Type	Required	Description
limit	number	No	Maximum number of items to return
offset	number	No	Number of items to skip

Response

{
  "items": [
    {
      "id": 1,
      "name": "Example Item",
      "description": "This is an example item"
    }
  ],
  "total": 1
}

If you’re not looking to build API reference documentation, you can delete this section by removing the api-reference folder.

Welcome

There are two ways to build API documentation: OpenAPI and MDX components. This starter shows examples using MDX components.

Authentication

API endpoints can be authenticated using various methods such as Bearer tokens, API keys, or OAuth.

"Authorization": "Bearer YOUR_TOKEN_HERE"