Production and Preview Deployments

Relevant source files

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

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

This documentation project utilizes the Mintlify platform, which provides two distinct environments for deploying and viewing content: a local preview environment for development and a production environment for the live documentation site. The local preview allows for rapid iteration and testing of changes, while the production deployment is automated through GitHub integration, ensuring that the live site is always up-to-date with the default repository branch.

The core of the documentation's structure and content is defined in markdown files and configured via the docs.json file. This includes navigation, theming, and API reference specifications. The entire system is designed for a streamlined developer experience, from writing content locally to publishing it automatically.

Sources: README.md, docs.json

Local Preview Environment

To facilitate development and content creation, a local preview server can be run. This allows authors to see their changes in real-time without affecting the live production site.

Sources: README.md:12-19

Setup and Execution

The local preview is powered by the Mintlify CLI.

1. Installation: The CLI must be installed globally via npm.

   npm i -g mint
   

2. Execution: To start the local server, run the mint dev command from the root of the repository (where docs.json is located).

   mint dev
   

3. Access: The local preview will be available at http://localhost:3000.

The following diagram illustrates the local development workflow.

Troubleshooting

Common issues with the local development environment can be resolved with the following steps:

• If the environment fails to start, update the CLI to the latest version using mint update.
• If a page returns a 404 error, ensure the mint dev command is being run from the same directory as a valid docs.json file.

Sources: README.md:25-28

Production Deployment

Production deployments are automated and managed through a GitHub App integration. This creates a continuous deployment pipeline that updates the live documentation site whenever changes are merged into the default branch.

Sources: README.md:21-23

Deployment Flow

The deployment process is triggered by a git push to the repository's default branch. The Mintlify GitHub App detects this push, builds the documentation site, and deploys the new version to production.

The sequence diagram below details the automated production deployment flow.

Configuration

The GitHub App integration is configured via the Mintlify dashboard. Once installed, it monitors the repository for changes to deploy.

Sources: README.md:21-23

Core Configuration (docs.json)

The docs.json file is the central configuration file for the documentation site. It controls the structure, appearance, and content sources for both preview and production builds.

Key	Description	Example Value
name	The name of the documentation site.	"Mint Starter Kit"
theme	The visual theme to use.	"mint"
colors	Primary, light, and dark color definitions for the theme.	{ "primary": "#16A34A", ... }
navigation	Defines the structure of the sidebar, including tabs, groups, and pages.	See docs.json:10-70
logo	Paths to the light and dark mode logo files.	{ "light": "/logo/light.svg", ... }
api-reference	Configuration for API documentation pages, often linking to an OpenAPI spec.	See docs.json:44-61

Sources: docs.json, essentials/settings.mdx

API Reference Deployment

The documentation includes API reference pages which are generated from an OpenAPI specification file. The docs.json file links to the markdown files that will render this content, and the API generation process uses the api-reference/openapi.json file as its data source.

The following diagram shows how the configuration and specification files relate to generate the final API documentation.

The openapi.json file defines the servers, paths, schemas, and security for the API. For example, it specifies a sandbox server and a bearer token authentication scheme.

{
  "servers": [
    {
      "url": "http://sandbox.mintlify.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ]
}

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

This structured approach ensures that the API documentation is consistent with the API's actual implementation and is deployed seamlessly with the rest of the content.

Sources: docs.json:44-61, api-reference/openapi.json