Running the Local Dev Server
Relevant source files
The following files were used as context for generating this wiki page:
The Mintlify local development server provides a way to preview documentation changes on your local machine before publishing them. It uses the Mintlify CLI to render the content defined in your project, including guides, API references, and customizations, creating a live preview accessible via a web browser. This allows for rapid iteration and verification of content and structural changes.
The server relies on a central configuration file, docs.json, to understand the project's structure, navigation, and theme settings. By running a simple command, developers can spin up a local instance of their documentation site that mirrors the production environment.
Sources: README.md:15-21, docs.json
Prerequisites and Installation
Before running the local server, you must install the Mintlify Command Line Interface (CLI). The CLI is distributed via npm and requires a Node.js environment.
CLI Installation
The Mintlify CLI can be installed globally using npm. This makes the mint command available in any terminal session.
npm i -g mint
Sources: README.md:15-17
The following diagram illustrates the one-time setup process for the development environment.
Sources: README.md:15-17
Launching the Server
To start the local development server, navigate to the root directory of your documentation project (the directory containing docs.json) and run the mint dev command.
mint dev
Upon successful execution, the server will start, and the local preview will be available at http://localhost:3000. The server watches for file changes and automatically reloads the preview.
Sources: README.md:19-23
This diagram shows the workflow for starting the server and viewing the documentation.
Sources: README.md:19-23, docs.json
Core Configuration
The behavior and content of the local server are dictated by the docs.json file. This file acts as the central manifest for the documentation project.
Key docs.json Properties
| Property | Description |
|---|---|
name | The name of the documentation project, displayed as the title. |
theme | Defines the visual theme, such as "mint". |
colors | Specifies the primary, light, and dark colors for the theme. |
navigation | Defines the structure of the documentation, including tabs, groups, and pages. The server uses this to build the sidebar and navigation controls. |
logo | Paths to the light and dark mode logo images. |
api-reference | Configuration for generating API documentation, often from an OpenAPI specification file. |
Sources: docs.json:3-82
The mint dev command parses docs.json to build the site structure. For example, the navigation object directly maps to the sidebar hierarchy, referencing content files like development.mdx and API reference pages.
This diagram shows how the mint dev command uses docs.json to assemble various content files into a coherent, navigable site.
Sources: README.md:20-21, docs.json:10-62
Content Rendering
The local server renders different types of content based on the project configuration.
Guide Pages
Standard content pages are written in Markdown (.md or .mdx) and are listed in the navigation array within docs.json. For instance, the entry "development" under the "Getting started" group tells the server to render the development.mdx file for that navigation link.
Sources: docs.json:20-22, development.mdx
API Reference
The server can also render API documentation from an OpenAPI specification file. The api-reference/openapi.json file defines endpoints, schemas, and security for a sample API. The navigation section in docs.json links to pages that will display this rendered OpenAPI content.
Sources: docs.json:45-58, api-reference/openapi.json
Troubleshooting
If the development server encounters issues, refer to the following common problems and solutions.
| Issue | Solution |
|---|---|
| Dev environment isn't running | Run mint update to ensure you have the most recent version of the CLI. |
| A page loads as a 404 error | Ensure the mint dev command is being run from a directory that contains a valid docs.json file. |
Sources: README.md:30-33
Summary
The local development server, powered by the Mintlify CLI, is an essential tool for creating and maintaining documentation. It provides a real-time preview of changes by interpreting the project's structure from docs.json and rendering content from Markdown and OpenAPI files. This local-first workflow enables developers and writers to build and verify high-quality documentation efficiently before publishing.
Sources: README.md:15-23