Versioning Your Documentation

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

Versioning within this documentation project is managed through two primary mechanisms: content versioning via Git integration for the documentation pages, and explicit versioning for the API specification. The documentation content's lifecycle is tied directly to the Git repository's default branch, while the API's version is declared within its OpenAPI specification file.

This page outlines how both documentation and API versions are managed and published. For more details on initial setup, see the Quickstart guide, and for local development processes, refer to the Development guide.

Content Versioning with Git

The versioning of documentation content (guides, tutorials, etc.) is implicitly handled by Git. The system is configured for continuous deployment from the default branch of the connected GitHub repository.

Sources: README.md:22-23

Publishing Workflow

Changes are published automatically when they are pushed to the repository's default branch. This process is facilitated by a Mintlify GitHub app that must be installed and configured for the repository. This Git-based approach ensures that the live documentation is always in sync with the main codebase.

The workflow is as follows:

1. A developer makes changes to the documentation files locally.
2. The developer commits and pushes the changes to the default branch on GitHub.
3. The Mintlify GitHub app detects the push event.
4. The app triggers a new deployment, publishing the updated content to the production documentation site.

This diagram illustrates the automated deployment pipeline.

Local Development and Preview

Before publishing, changes can be previewed locally using the Mintlify CLI. Running mint dev in the root directory (where docs.json is located) starts a local server at http://localhost:3000, allowing developers to review their changes before pushing them to the default branch. This step is crucial for catching errors and ensuring quality before a new "version" of the documentation goes live.

Sources: README.md:13-19, development.mdx

API Specification Versioning

The API documentation is generated from an OpenAPI specification file, which has its own explicit versioning. This ensures that the API reference is accurate for a specific release of the API.

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

Version Declaration

The API version is declared in the info.version field within the api-reference/openapi.json file. This follows the OpenAPI 3.1.0 specification.

{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenAPI Plant Store",
    "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  ...
}

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

The current version is set to 1.0.0. Any updates to the API that require documentation changes should be accompanied by an update to this version number and the corresponding changes in the paths, components, or other sections of the OpenAPI file.

Integration into Documentation

The docs.json configuration file integrates the versioned API specification into the main documentation site under the "API reference" tab. It groups all API-related pages, which are generated from the api-reference/openapi.json file.

The following diagram shows how the docs.json file structures the navigation to include the API reference, which in turn is based on the versioned OpenAPI file.

Versioning Components Summary

The table below summarizes the key files and properties involved in versioning the documentation and the API.

Component	Governed By	Key Element	Description
Documentation Content	README.md, Git Workflow	Default branch push	Pushing to the default branch automatically deploys new content.
API Specification	api-reference/openapi.json	info.version	The semantic version of the API, currently "1.0.0".
Documentation Structure	docs.json	navigation.tabs	Defines how the versioned API reference is included in the site navigation.
Initial Setup	quickstart.mdx	Repository setup	The quickstart process involves setting up the Git repository for version control.

Sources: README.md:22-23, api-reference/openapi.json:10, docs.json:13-15, quickstart.mdx

Conclusion

The project employs a dual-strategy for versioning. Documentation content relies on a Git-based, continuous deployment model where the default branch represents the latest version. In contrast, the API reference uses explicit semantic versioning defined within its OpenAPI specification. This separation allows documentation to be updated fluidly while the API reference remains tied to specific, stable releases.