Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the guidelines for contributing to the Mintlify Starter Kit documentation project. The project serves as a template for creating and deploying documentation using the Mintlify platform. Contributions primarily involve setting up the local development environment, modifying documentation content, structuring navigation, and updating the API reference specification.
Adhering to these guidelines ensures that contributions are consistent, well-structured, and integrate smoothly with the existing documentation framework. The core of the project's configuration and structure is managed through the docs.json file, which defines navigation, theme, and other metadata.
1. Getting Started: Local Development
Before making any changes, you must set up a local development environment to preview your work. This process relies on the Mintlify Command Line Interface (CLI).
Sources: README.md:12-20
1.1. Environment Setup
The primary dependency is the Mintlify CLI, which must be installed globally via npm.
npm i -g mint
Sources: README.md:15
Once installed, you can start the local development server by running mint dev from the root of the repository (where docs.json is located).
mint dev
Sources: README.md:19
The local preview will be available at http://localhost:3000. If the environment fails to start, running mint update can resolve issues by ensuring you have the latest version of the CLI.
Sources: README.md:21, README.md:26
1.2. Development Workflow
The following diagram illustrates the standard development workflow for making and previewing changes.
This diagram shows the process of setting up the Mintlify CLI, starting the local development server, and iterating on changes.
Sources: README.md:12-21
2. Project Structure and Configuration
The project's structure, appearance, and navigation are defined in the docs.json file. Understanding this file is crucial for making structural contributions.
Sources: docs.json
2.1. Core Configuration (docs.json)
The docs.json file contains several key-value pairs that configure the documentation site.
| Key | Description | Example Value |
|---|---|---|
name | The name of the documentation project. | "Mint Starter Kit" |
theme | The visual theme to use. | "mint" |
colors | Defines the primary, light, and dark colors for the theme. | { "primary": "#16A34A", ... } |
favicon | Path to the site's favicon. | "/favicon.svg" |
logo | Paths to the light and dark mode logos. | { "light": "/logo/light.svg", ... } |
navigation | An object that defines the entire navigation structure, including tabs and groups. | { "tabs": [...] } |
footer | Defines social media links for the footer. | { "socials": { "x": "...", ... } } |
Sources: docs.json:3-9, docs.json:10, docs.json:63-66, docs.json:73-77
2.2. Navigation Structure
The navigation is defined under the navigation key in docs.json. It is organized into tabs, which contain groups of pages.
The following diagram visualizes the navigation hierarchy defined in docs.json.
This diagram shows how pages are organized into groups and tabs for the site's navigation.
Sources: docs.json:10-58
To add a new page, you must add its file name (without the extension) to the appropriate pages array within a group.
3. API Reference Contributions
The API reference section is generated from an OpenAPI specification file. All changes to the API documentation must be made in this file.
Sources: api-reference/openapi.json
3.1. OpenAPI Specification
The API is defined in api-reference/openapi.json using the OpenAPI 3.1.0 standard. This file includes API information, server URLs, paths, and component schemas.
Sources: api-reference/openapi.json:2-9
The API requires bearer token authentication, as specified in the security and securitySchemes components.
"security": [
{
"bearerAuth": []
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
Sources: api-reference/openapi.json:15-19, api-reference/openapi.json:189-195
3.2. API Endpoints
The available endpoints are defined under the paths object.
| 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 information. |
Sources: api-reference/openapi.json:21, api-reference/openapi.json:23, api-reference/openapi.json:66, api-reference/openapi.json:107, api-reference/openapi.json:134
The following sequence diagram shows the interaction for creating a new plant.
This diagram illustrates the request and response flow for the POST /plants endpoint.
Sources: api-reference/openapi.json:11, api-reference/openapi.json:65-98
3.3. Data Schemas
Data models are defined under components.schemas. The main schemas are Plant, NewPlant, and Error.
The relationship between NewPlant and Plant is that NewPlant extends Plant with an id field.
This diagram shows that the NewPlant schema inherits all properties from the Plant schema and adds an id.
Sources: api-reference/openapi.json:151-165, api-reference/openapi.json:166-180
4. Publishing Changes
Changes are published automatically after being pushed to the repository's default branch. This process is managed by the Mintlify GitHub app.
The deployment flow is as follows:
- A developer pushes committed changes to the default branch on GitHub.
- The Mintlify GitHub app detects the push event.
- The app triggers a new deployment.
- Changes are propagated to the production documentation site.
Sources: README.md:22-24
This diagram shows the automated deployment pipeline initiated by a push to the default branch.
Sources: README.md:22-24
Summary
Contributing to this project involves a straightforward workflow: setting up the local environment with the Mintlify CLI, making changes to content or configuration files, and previewing them locally. Structural changes to navigation are done in docs.json, while API documentation updates are made in api-reference/openapi.json. Once changes are finalized, pushing them to the default branch automatically deploys them to the live site.