Setting Site Metadata

Relevant source files

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

• docs.json
• api-reference/openapi.json
• README.md
• essentials/settings.mdx
• essentials/navigation.mdx

Site metadata configuration is central to customizing the appearance, branding, and navigational structure of the documentation. This is primarily managed through the docs.json file, which acts as the main configuration hub for the entire site. For API documentation, metadata is further defined within an OpenAPI specification file, such as api-reference/openapi.json, which populates the API reference sections with titles, descriptions, and server information.

This document outlines the key configuration objects and properties used to define site metadata. It covers general settings, branding, navigation, and API-specific metadata, all derived from the project's configuration files. Understanding these settings is crucial for customizing the documentation to fit specific project needs.

Core Configuration (docs.json)

All primary site metadata is defined within the docs.json file located at the root of the project. This file controls everything from the site name and theme to the complex structure of the navigation sidebar and footer links. The Mintlify CLI uses this file to build and render the documentation locally.

Sources: README.md:17-19, docs.json

The following diagram illustrates the top-level configuration keys in docs.json that define site metadata.

Basic Metadata

These properties define the fundamental identity and appearance of the documentation site.

Key	Description	Example Value
name	The display name of the documentation site.	"Mint Starter Kit"
theme	The visual theme to apply.	"mint"
favicon	The path to the site's favicon file.	"/favicon.svg"

Sources: docs.json:3-10, essentials/settings.mdx

Branding and Appearance

Branding is controlled via the colors and logo objects, allowing for customization of the site's color palette and logos for light and dark modes.

Color Configuration

"colors": {
  "primary": "#16A34A",
  "light": "#07C983",
  "dark": "#15803D"
}

Sources: docs.json:5-9

Logo Configuration

"logo": {
  "light": "/logo/light.svg",
  "dark": "/logo/dark.svg"
}

Sources: docs.json:76-79

Navigation Structure

The navigation object defines the entire sidebar and top-level tab structure. It is a hierarchical configuration that organizes content into tabs, groups, and pages.

Sources: docs.json:11-75, essentials/navigation.mdx

This diagram shows the hierarchical structure of the navigation object.

The navigation object contains two main parts:

1. tabs: An array defining the main content sections. Each tab contains groups of pages.
2. global.anchors: Defines links that appear at the bottom of the navigation sidebar, outside of any specific group.

Navbar and Footer

The navbar and footer objects control the links and elements in the top navigation bar and the site footer, respectively.

Navbar Configuration

Key	Type	Description
links	Array	An array of link objects, each with a label and href.
primary	Object	A configuration for the primary call-to-action button, with type, label, and href.

Sources: docs.json:80-89

Footer Configuration
The footer.socials object contains key-value pairs where the key is the social media platform (e.g., x, github) and the value is the URL to the profile.

"footer": {
  "socials": {
    "x": "https://x.com/mintlify",
    "github": "https://github.com/mintlify%22%2C
    "linkedin": "https://linkedin.com/company/mintlify"
  }
}

Sources: docs.json:100-106

API Metadata (openapi.json)

For the API reference, metadata is sourced from an OpenAPI specification file, defined in this repository as api-reference/openapi.json. This file provides essential information about the API, such as its title, description, version, and server endpoints.

Sources: api-reference/openapi.json

API Information

The info object within the OpenAPI spec contains high-level metadata about the API.

Key	Description	Example Value
title	The title of the API.	"OpenAPI Plant Store"
description	A short description of the API.	"A sample API that uses a plant store..."
version	The current version of the API.	"1.0.0"

Sources: api-reference/openapi.json:3-9

Server Configuration

The servers array specifies the base URLs for the API environments.

"servers": [
  {
    "url": "http://sandbox.mintlify.com"
  }
]

This configuration populates the base URL selector in the API reference documentation, allowing users to target different environments.
Sources: api-reference/openapi.json:10-14

Content and Tooling Metadata

The docs.json file also defines metadata related to content interaction tools.

Contextual Tools

The contextual.options array lists the AI and developer tools that can be enabled for interaction with code blocks and content.

Option	Description
copy	Enables a copy button.
chatgpt	Enables "Ask ChatGPT".
claude	Enables "Ask Claude".
cursor	Enables "Open in Cursor".
vscode	Enables "Open in VS Code".

Sources: docs.json:90-99

Conclusion

Setting site metadata is a declarative process managed through two key files: docs.json for the overall site structure, branding, and navigation, and api-reference/openapi.json for API-specific details. By modifying these files, developers can comprehensively customize the documentation's appearance and content organization. The structured nature of these configurations provides a powerful and maintainable way to manage the documentation portal's metadata.

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