Quick Start Guide

Relevant source files

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

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

This guide provides instructions on how to set up, run, and customize the Mintlify Starter Kit. The starter kit is a template repository designed to help you quickly deploy and build your documentation. It includes examples of guide pages, API references, and various customizations.

The project is configured through a central docs.json file, which defines the navigation, theme, and other metadata. Local development is facilitated by the Mintlify CLI, allowing for live previews of changes before they are published. Publishing is automated through a GitHub app that deploys changes upon pushing to the default branch.

Getting Started

To begin, you must create a new repository from the mintlify-docs template.

Sources: README.md:3-5

Local Development Setup

To preview documentation changes locally, you need to install the Mintlify CLI and run the development server.

1. Install the CLI: The Mintlify CLI is a global NPM package.

   npm i -g mint
   

   Sources: README.md:15-17

2. Run the Dev Server: Navigate to the root of your project (where docs.json is located) and run:

   mint dev
   

   Sources: README.md:21-23

3. Preview: Your local documentation will be available at http://localhost:3000.
   Sources: README.md:25

The following diagram illustrates the local development workflow.

Project Configuration

The core configuration for the documentation site is managed in the docs.json file. This file controls the theme, navigation structure, branding, and other settings.

Sources: docs.json

Key Configuration Properties

Key	Description
name	The name of the documentation site, "Mint Starter Kit".
theme	The visual theme to use, set to "mint".
colors	Defines the primary, light, and dark colors for the theme.
favicon	Path to the favicon file.
navigation	Defines the structure of the documentation sidebar, including tabs, groups, and pages.
logo	Paths to the light and dark mode logos.
navbar	Configuration for the top navigation bar links.
footer	Defines social media links for the footer.

Sources: docs.json:3-73

Navigation Structure

The navigation object in docs.json defines how the documentation pages are organized. It uses a system of tabs, groups, and pages. The "Getting started" group, for instance, includes pages like index, quickstart, and development.

The diagram below shows the high-level structure of the docs.json file.

API Reference

The starter kit includes a pre-configured API reference section powered by an OpenAPI specification file.

OpenAPI Specification

The API documentation is generated from api-reference/openapi.json. This file defines the API's endpoints, schemas, and security requirements.

• Title: OpenAPI Plant Store
• Version: 1.0.0
• Server: http://sandbox.mintlify.com
• Security: Uses Bearer Token authentication (bearerAuth).

Sources: api-reference/openapi.json:3-14, 18-23

API Endpoints

The sample API provides endpoints for managing plants.

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 based on the ID.
POST	/plant/webhook	Webhook for notifications about new plants.

Sources: api-reference/openapi.json:24-118

The following sequence diagram shows the flow for retrieving all plants.

API Data Models

The openapi.json file defines the data structures used by the API in the components/schemas section.

Sources: api-reference/openapi.json:121-169

Publishing Changes

Changes are published automatically by installing the Mintlify GitHub app. When code is pushed to the default branch of your repository, the changes are deployed to your production documentation site.

Sources: README.md:29-31

The deployment flow is as follows:

Troubleshooting

If you encounter issues, consider the following:

• Dev environment not running: Run mint update to get the latest CLI version.
• 404 errors: Ensure you are running mint dev in the directory containing docs.json.

Sources: README.md:35-38