Deployment Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• docs.json
• api-reference/openapi.json
• development.mdx
• quickstart.mdx

This document provides a technical overview of the development and deployment process for the Mintlify documentation project. The system leverages the Mintlify CLI for local development and a dedicated GitHub application for automated production deployments. The entire documentation site, including guides and API references, is configured through a central docs.json file and built from Markdown (.mdx) and OpenAPI specification files.

The deployment pipeline is designed for simplicity and automation. Local changes can be previewed in real-time, and production updates are triggered automatically upon pushing code to the repository's default branch. This ensures that the live documentation is always in sync with the source content.

Local Development and Preview

Local development is facilitated by the Mintlify Command Line Interface (CLI). This tool allows developers to run a local server that hot-reloads changes, providing an instant preview of the documentation site.

Sources: README.md:13-21, development.mdx

Setup and Execution

1. Install the CLI: The Mintlify CLI must be installed globally via npm.

   npm i -g mint
   

   Sources: README.md:16, development.mdx:11

2. Run the Dev Server: To start the local preview server, run the mint dev command from the root of the project (where docs.json is located).

   mint dev
   

   Sources: README.md:19, development.mdx:17

3. Access the Preview: The local documentation site becomes available at http://localhost:3000.

The following diagram illustrates the local development workflow.

Troubleshooting

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 on a page typically indicates that the mint dev command was run from a directory that does not contain a valid docs.json file.

Sources: README.md:28-31

Production Deployment

Production deployments are fully automated through the Mintlify GitHub application. Once installed and configured for the repository, the app monitors for changes and handles the deployment process.

Sources: README.md:23-25

Deployment Trigger

The deployment process is triggered automatically when code is pushed to the repository's default branch. The GitHub app detects the push event, builds the documentation site from the source files, and deploys it to the production environment.

The sequence diagram below outlines the automated deployment process.

Configuration and Structure

The structure, navigation, and appearance of the deployed documentation are controlled by the docs.json file. This file acts as the central manifest for the project.

Sources: docs.json

Key Configuration Properties

Property	Description	Source
name	The name of the documentation site, "Mint Starter Kit".	[docs.json:4](https://github.com/evenetehesort/mintlify-docs/blob/HEAD/docs.json#L4)
theme	The visual theme to apply, set to "mint".	[docs.json:3](https://github.com/evenetehesort/mintlify-docs/blob/HEAD/docs.json#L3)
colors	Defines the primary, light, and dark colors for the theme.	[docs.json:5-9](https://github.com/evenetehesort/mintlify-docs/blob/HEAD/docs.json#L5-L9)
navigation	Configures the entire site navigation, including tabs, groups, and pages.	[docs.json:11-53](https://github.com/evenetehesort/mintlify-docs/blob/HEAD/docs.json#L11-L53)
logo	Specifies paths to the light and dark mode logos.	[docs.json:64-67](https://github.com/evenetehesort/mintlify-docs/blob/HEAD/docs.json#L64-L67)
footer	Defines social media links for the site footer.	[docs.json:82-86](https://github.com/evenetehesort/mintlify-docs/blob/HEAD/docs.json#L82-L86)

Navigation Structure

The navigation object in docs.json defines how content files are organized and presented to the user. It uses a system of tabs and groups to create a hierarchical menu. For example, the "Guides" tab contains groups like "Getting started" and "Customization", which in turn list the specific .mdx pages to display.

The API reference section is also defined here, linking to an introduction page and specific endpoint examples.

API Reference Generation

The API reference pages are automatically generated from an OpenAPI 3.1.0 specification file. This project uses api-reference/openapi.json to define the API for a sample "Plant Store".

Sources: api-reference/openapi.json, docs.json:38-52

The Mintlify build process parses this file to create interactive documentation for each endpoint, including request/response schemas, parameters, and security definitions.

API Endpoints

The OpenAPI specification defines the following paths:

Method	Path	Description
GET	/plants	Returns all plants from the system.
POST	/plants	Creates a new plant in the store.
DELETE	/plants/{id}	Deletes a single plant by its ID.

Sources: api-reference/openapi.json:20-103

Webhooks

A webhook is also defined to notify external systems about new plants.

Method	Path	Description
POST	/plant/webhook	Receives information about a new plant added to the store.

Sources: api-reference/openapi.json:104-122

Data Schemas

The API relies on several data schemas defined in the components section of the OpenAPI file.