Introduction to Components

Relevant source files

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

• README.md
• docs.json
• api-reference/openapi.json
• essentials/markdown.mdx
• essentials/code.mdx

This document provides a technical overview of the primary components that constitute the Mintlify Starter Kit. The project is designed to provide a foundational structure for creating and deploying documentation. The core components include the main configuration file (docs.json), content files for guides and references, and an OpenAPI specification for generating API documentation. These elements work together to define the structure, appearance, and content of the final documentation site.

The main components can be categorized into configuration, content, and API specification. The docs.json file acts as the central manifest, defining navigation, theme, and branding. Content is organized into pages like guides and API examples, referenced within the navigation structure. The API documentation is automatically generated from the api-reference/openapi.json file, which defines endpoints, data models, and security schemes.

Core Configuration (docs.json)

The docs.json file is the central configuration component for the documentation site. It defines the overall structure, branding, navigation, and other metadata.

Sources: docs.json

The diagram below illustrates the top-level structure of the docs.json configuration file.

Navigation Structure

The navigation object within docs.json defines the layout of the documentation sidebar, including tabs, groups, and pages. The starter kit is configured with two main tabs: "Guides" and "API reference".

Sources: docs.json:11-61

Tab	Group	Pages
Guides	Getting started	index, quickstart, development
	Customization	essentials/settings, essentials/navigation
	Writing content	essentials/markdown, essentials/code, essentials/images, essentials/reusable-snippets
	AI tools	ai-tools/cursor, ai-tools/claude-code, ai-tools/windsurf
API reference	API documentation	api-reference/introduction
	Endpoint examples	api-reference/endpoint/get, api-reference/endpoint/create, api-reference/endpoint/delete, api-reference/endpoint/webhook

Sources: docs.json:13-59

Branding and Theming

Basic branding and theme settings are controlled via top-level keys.

Key	Description	Example Value
theme	The visual theme for the documentation.	"mint"
name	The name of the project.	"Mint Starter Kit"
colors	Primary, light, and dark theme colors.	{"primary": "#16A34A", ...}
logo	Paths to light and dark mode logo images.	{"light": "/logo/light.svg", ...}
favicon	Path to the site's favicon.	"/favicon.svg"

Sources: docs.json:3-10, docs.json:79-82

API Reference Components (openapi.json)

The API documentation is generated from an OpenAPI 3.1.0 specification file. This file defines the available endpoints, their parameters, expected responses, and the data models (schemas) used in the API. The server for this sample API is http://sandbox.mintlify.com.

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

Data Schemas

The API uses several data schemas to define the structure of requests and responses. The primary schemas are Plant, NewPlant, and Error.

The relationship between these schemas is shown below. NewPlant extends Plant by adding an id property.

Plant Schema

This schema represents a plant object. The name property is required.

Property	Type	Description
name	string	The name of the plant
tag	string	Tag to specify the type
Sources: api-reference/openapi.json:115-128

NewPlant Schema

This schema is a composition of the Plant schema and adds a required id property.

Property	Type	Description
id	integer	Identification number of the plant
name	string	(Inherited from Plant)
tag	string	(Inherited from Plant)
Sources: api-reference/openapi.json:129-146

API Endpoints

The API provides endpoints for managing plants and a webhook for receiving notifications. All endpoints are secured with Bearer Token authentication.

Sources: api-reference/openapi.json:16-18, api-reference/openapi.json:20-112

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 new plant notifications.
Sources: api-reference/openapi.json:21-112

The following sequence diagram illustrates the flow for creating a new plant using the POST /plants endpoint.

Content and Development Components

The starter kit includes components for writing content and a local development environment to preview changes.

Content Pages

The documentation is composed of MDX files which are organized into groups as defined in docs.json. The starter kit provides examples for various content types:

• Guides: Standard documentation pages (quickstart.mdx, development.mdx).
• Customization: Pages explaining how to configure the docs (essentials/navigation.mdx).
• Writing Content: Examples of using Markdown, code blocks, and other features (essentials/markdown.mdx, essentials/code.mdx).

Sources: docs.json:20-40, README.md:5-10

Development Workflow

The Mintlify CLI is a key component for local development. It allows authors to run a local server and preview documentation changes in real-time.

Sources: README.md:12-14

The local development process follows these steps:

Summary

The Mintlify Starter Kit is a well-structured project that relies on a few key components. The docs.json file serves as the central point of configuration, defining the site's structure and appearance. The api-reference/openapi.json file provides a robust, standardized way to generate interactive API documentation. Finally, the content itself is created in .mdx files, with a local development workflow powered by the Mintlify CLI to facilitate writing and previewing. Together, these components provide a comprehensive solution for building and maintaining technical documentation.