Welcome to the Mintlify Starter Kit
Relevant source files
The following files were used as context for generating this wiki page:
The Mintlify Starter Kit provides a foundational template for creating, customizing, and deploying documentation. It is designed to help users quickly set up a documentation site complete with guide pages, API references, and various customizations. The starter kit includes examples of essential features and popular components to streamline the documentation process.
This project is configured primarily through the docs.json file, which defines the structure, appearance, and navigation of the documentation site. Local development is facilitated by the Mintlify CLI, allowing for real-time previews of changes before they are published. Deployment is automated through a GitHub app, which pushes changes from the default branch to the live site.
Sources: README.md:3-11, docs.json
Getting Started
To begin using the starter kit, you must first copy the template repository. The primary workflow involves local development for previewing changes and then publishing them by pushing to the default branch of your repository.
Sources: README.md:5-7
Local Development
Local development is managed by the Mintlify CLI. You must install the CLI globally via npm and then run the dev command from the root of the project.
- Install Mintlify CLI:
npm i -g mint - Run the development server:
mint dev - Preview: View the documentation site at
http://localhost:3000.
The following diagram illustrates the local development process.
Diagram illustrating the local development cycle.
If the development environment fails to start, running mint update can resolve the issue by ensuring the CLI is on the latest version. A 404 error typically indicates that the mint dev command was not run from the directory containing docs.json.
Sources: README.md:15-25, quickstart.mdx
Publishing Changes
Changes are published automatically when they are pushed to the repository's default branch. This process requires installing the Mintlify GitHub app, which connects your repository to the Mintlify deployment service.
Diagram showing the automated deployment workflow.
Sources: README.md:27-29
Project Configuration (docs.json)
The core configuration for the documentation site is located in docs.json. This file controls everything from the theme and colors to the navigation structure and footer links.
Sources: docs.json
The diagram below shows the top-level structure of the docs.json file.
High-level structure of the docs.json configuration file.
Key Configuration Properties
| Property | Description | Example Value |
|---|---|---|
name | The name of the documentation site. | "Mint Starter Kit" |
theme | The visual theme to use. | "mint" |
colors | Defines the primary, light, and dark colors for the theme. | {"primary": "#16A34A", ...} |
favicon | Path to the favicon image. | "/favicon.svg" |
logo | Paths to the light and dark mode logo images. | {"light": "/logo/light.svg", ...} |
navbar | Configures links and a primary call-to-action button in the top navigation bar. | {"links": [...], "primary": {...}} |
footer | Defines social media links for the site footer. | {"socials": {"x": "...", ...}} |
contextual | Configures options for interacting with code blocks (e.g., copy, view, chatgpt). | ["copy", "view", "chatgpt", ...] |
Sources: docs.json:2-12, 65-94
Navigation Structure
The navigation object within docs.json defines the layout of the documentation pages, organized into tabs and groups. This starter kit is configured with two main tabs: "Guides" and "API reference".
The following diagram visualizes the navigation hierarchy defined in docs.json.
Visualization of the documentation structure from docs.json.
Sources: docs.json:13-64, index.mdx
API Reference (openapi.json)
The starter kit includes a sample API reference generated from an OpenAPI 3.1.0 specification file located at api-reference/openapi.json. This file defines the API's endpoints, data models, and security schemes.
Sources: api-reference/openapi.json, docs.json:42-58
API Server and Security
- Server: The API is hosted at
http://sandbox.mintlify.com. - Security: The API uses Bearer Token authentication (
bearerAuth).
Sources: api-reference/openapi.json:12-20
Data Models (Schemas)
The API uses several data schemas to define the structure of requests and responses. The primary schemas are Plant, NewPlant, and Error.
Class diagram of the main data schemas defined in openapi.json.
- Plant: The base object representing a plant, with a required
name. - NewPlant: Extends
Plantand adds a requiredid. This is used when creating a new plant. - Error: A standard error object with a code and message.
Sources: api-reference/openapi.json:125-177
Endpoints
The API provides endpoints for managing plants.
GET /plants
Returns a list of all plants. It accepts an optional limit query parameter.
Sequence diagram for fetching all plants.
Sources: api-reference/openapi.json:23-55
POST /plants
Creates a new plant. The request body must contain a NewPlant object.
Sequence diagram for creating a new plant.
Sources: api-reference/openapi.json:56-88
DELETE /plants/{id}
Deletes a specific plant by its ID.
Sequence diagram for deleting a plant.
Sources: api-reference/openapi.json:91-114
Webhooks
The API defines a webhook to notify clients about new plants.
POST /plant/webhook
This webhook is triggered when a new plant is added to the store, sending a NewPlant object in the request body.
Sequence diagram for the new plant webhook.
Sources: api-reference/openapi.json:116-124