Prerequisites

Relevant source files

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

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

This document outlines the necessary prerequisites for setting up, running, and customizing the Mintlify Starter Kit. The primary requirements involve installing the Mintlify Command Line Interface (CLI) for local development and understanding the core project configuration file, docs.json, which governs the structure and appearance of the documentation.

The starter kit is designed to provide a foundation for documentation, including guides, API references, and various customizations. A proper setup ensures that developers can preview changes locally before publishing them. The project relies on a specific file structure, defined in the Navigation settings, to organize content.

Development Environment Setup

To preview documentation changes locally, you must install the Mintlify CLI. This tool provides a local development server that reflects changes in real-time.

Sources: README.md:12-14

Installation and Usage

1. Install the CLI: The Mintlify CLI is an npm package. Install it globally using the following command:

   npm i -g mint
   

   Sources: README.md:15-17

2. Run the Development Server: Navigate to the root of your documentation project (the directory containing docs.json) and run:

   mint dev
   

   This command starts a local server, typically available at http://localhost:3000.
   Sources: README.md:19-23

3. Update the CLI: If you encounter issues with the development environment, ensure you have the latest version of the CLI by running:

   mint update
   

   Sources: README.md:30-31

The following diagram illustrates the local development workflow.

This diagram shows the steps for setting up the local development environment.
Sources: README.md:12-25

Core Project Configuration

The primary configuration for the documentation site is managed through the docs.json file located at the project root. This file defines the project's name, theme, navigation structure, and other metadata.

Sources: docs.json, README.md:21-22

docs.json Structure

The docs.json file contains several key-value pairs that control the documentation's behavior and appearance.

Key	Description
$schema	Specifies the JSON schema for validation and autocompletion.
theme	Defines the visual theme of the documentation. The value is "mint".
name	The name of the project, displayed on the documentation site. Set to "Mint Starter Kit".
colors	Defines the primary, light, and dark colors for the theme.
favicon	Path to the favicon image file.
navigation	An object that defines the structure of the sidebar navigation, including tabs, groups, and pages.
logo	Paths to the logo for light and dark modes.
navbar	Configuration for the top navigation bar links.
contextual	Defines options available in the contextual menu for code blocks (e.g., copy, chatgpt).
footer	Contains links to social media profiles.

Sources: docs.json:2-100

Navigation Configuration

The navigation object within docs.json is critical for organizing content. It uses a hierarchical structure of tabs, groups, and pages to build the sidebar.

• Tabs: Top-level sections like "Guides" and "API reference".
• Groups: Collections of pages within a tab, such as "Getting started" or "Endpoint examples".
• Pages: Individual markdown files that represent a documentation page.

Sources: docs.json:13-63

The following diagram visualizes the navigation hierarchy defined in docs.json.

This graph shows the hierarchical structure of the documentation navigation.
Sources: docs.json:14-62

API Reference Integration

The API reference pages are generated from an OpenAPI specification file. The starter kit includes a sample openapi.json file for this purpose.

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

OpenAPI Specification

The project uses an OpenAPI 3.1.0 specification to define its API. The main configuration includes metadata, server URLs, and security schemes.

• Title: OpenAPI Plant Store
• Version: 1.0.0
• Server URL: http://sandbox.mintlify.com
• Security: Bearer Authentication is defined as a security scheme.

Sources: api-reference/openapi.json:2-19

API Schema Definitions

Data models for API requests and responses are defined under components.schemas in the openapi.json file. The starter kit includes schemas for Plant, NewPlant, and Error.

The relationship between these schemas is visualized in the class diagram below.

This diagram shows that NewPlant extends Plant with an additional id field.
Sources: api-reference/openapi.json:120-167

API Endpoint Flow

The paths object defines the available API endpoints. As an example, the GET /plants endpoint retrieves a list of plants.

The sequence diagram below illustrates a successful call to this endpoint.

This diagram shows the request-response flow for the GET /plants endpoint.
Sources: api-reference/openapi.json:23-58

Summary

The prerequisites for working with the Mintlify Starter Kit are straightforward. A developer needs Node.js and npm to install the Mintlify CLI, which is essential for local development and previewing. The core of the project's structure is defined in docs.json, which dictates navigation and appearance. For API documentation, a valid OpenAPI specification file like api-reference/openapi.json is required to automatically generate reference pages. Understanding these components is key to effectively customizing and extending the documentation.