Theme and Style Customization
Relevant source files
The following files were used as context for generating this wiki page:
Theme and style customization for the documentation site is managed centrally through the docs.json configuration file. This file allows for project-wide changes to the visual appearance, branding, and structural layout elements like the navigation and footer. By modifying this single file, you can define the color palette, set logos, and structure the entire user navigation experience without writing any custom CSS or scripts.
The customization options range from high-level theme selection to granular control over colors, links, and social media icons. The system is designed to apply these styles consistently across all content, including standard guide pages and auto-generated API reference documentation. Further documentation on these topics can be found on the Settings and Navigation pages.
Sources: README.md:16-18, docs.json, essentials/settings.mdx, essentials/navigation.mdx
Core Configuration: docs.json
The docs.json file is the single source of truth for all theme and style settings. It contains several top-level keys that control different aspects of the site's appearance and structure.
The following diagram illustrates the key configuration areas within docs.json related to theming and styling.
Sources: docs.json
Key Customization Properties
The table below summarizes the main properties in docs.json for customizing the site's look and feel.
| Property | Description |
|---|---|
theme | Specifies the base theme to use. Set to "mint". |
name | The name of the documentation project, displayed prominently. |
colors | An object defining the primary, light, and dark colors for the theme. |
favicon | The path to the website's favicon image. |
logo | An object specifying paths for light and dark mode logos. |
navigation | Defines the structure of the main sidebar navigation, including tabs and groups. |
navbar | Configures the top navigation bar, including custom links and a primary button. |
footer | Configures the site footer, primarily for social media links. |
Sources: docs.json:2-93
Theming and Colors
The visual theme is controlled by the theme and colors properties. The project is configured to use the "mint" theme, and its color scheme can be customized.
Sources: docs.json:2-8
Color Palette
The colors object allows you to define a specific color palette that will be applied throughout the documentation site.
| Key | Description | Value |
|---|---|---|
primary | The main accent color, used for links, buttons, and active states. | #16A34A |
light | A lighter shade, potentially used for hover effects or secondary elements. | #07C983 |
dark | A darker shade, used for text or other primary UI components. | #15803D |
{
"colors": {
"primary": "#16A34A",
"light": "#07C983",
"dark": "#15803D"
}
}
This color scheme is applied globally, ensuring a consistent appearance on all pages, including those generated from OpenAPI specifications.
Sources: docs.json:4-8, api-reference/openapi.json
Branding Assets
Branding is managed via the favicon and logo properties, which point to static image assets.
Sources: docs.json:9, docs.json:65-68
Favicon
The site's favicon is specified by a single path.
{
"favicon": "/favicon.svg"
}
Sources: docs.json:9, favicon.svg
Logo
The logo object supports different assets for light and dark display modes, ensuring visibility in either theme.
{
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg"
}
}
The system will automatically switch between light.svg and dark.svg based on the user's OS or browser settings.
Sources: docs.json:65-68, logo/light.svg, logo/dark.svg
Structural Customization
Beyond colors and logos, docs.json defines the layout and content of major structural elements like the navigation bar, page navigation tree, and footer.
Navigation Bar (Navbar)
The navbar object configures the top-most navigation bar. It supports adding an array of standard links and a single primary call-to-action button.
| Key | Type | Description |
|---|---|---|
links | Array | A list of link objects, each with a label and href. |
primary | Object | A single link object styled as a primary button, with type, label, and href. |
{
"navbar": {
"links": [
{
"label": "Support",
"href": "mailto:hi@mintlify.com"
}
],
"primary": {
"type": "button",
"label": "Dashboard",
"href": "https://dashboard.mintlify.com"
}
}
}
Sources: docs.json:69-79
Page Navigation
The main sidebar navigation is defined by the navigation object. It organizes content into tabs and groups, creating a hierarchical structure for browsing the documentation.
The diagram below shows the navigation structure defined in docs.json.
This configuration directly maps to the user-facing sidebar, making content discovery intuitive. The paths correspond to the .mdx files in the repository.
Sources: docs.json:10-53, essentials/navigation.mdx
Footer
The footer object is used to configure social media links that appear at the bottom of the page. It contains a socials object where keys are the social media platform (e.g., x, github) and values are the corresponding profile URLs.
{
"footer": {
"socials": {
"x": "https://x.com/mintlify",
"github": "https://github.com/mintlify%22%2C
"linkedin": "https://linkedin.com/company/mintlify"
}
}
}
Sources: docs.json:89-93