Creating Guide Pages

Relevant source files

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

• docs.json
• README.md
• api-reference/openapi.json
• quickstart.mdx
• development.mdx

Guide pages form the core narrative and instructional content of the documentation. They are organized into logical groups and are defined primarily through the central docs.json configuration file. This system allows for a clear separation between documentation structure, defined in JSON, and documentation content, written in Markdown files.

The starter kit provides examples of guide pages covering topics from getting started to customization and content writing. These pages are rendered within the "Guides" tab of the main navigation, distinct from other sections like the API Reference.

Sources: README.md:5-9, docs.json:12-14

Navigation and Structure

The structure, grouping, and navigation of all guide pages are managed within the navigation object in docs.json. This configuration file acts as the single source of truth for how documentation pages are presented to the user.

Sources: docs.json:11-73

Navigation Hierarchy

The navigation is organized into a hierarchy of tabs, groups, and pages. For guide pages, these are configured under a tab with the name "Guides".

The diagram below illustrates the hierarchical structure for defining documentation navigation.

This diagram shows how the navigation object in docs.json contains tabs, which in turn contain groups of pages.

Sources: docs.json:12-49

Configuration Details

The navigation object uses specific keys to build the hierarchy.

Element	Type	Description
tabs	Array	An array of tab objects, each representing a top-level section like "Guides" or "API reference".
tab	String	The display name for a top-level navigation tab.
groups	Array	An array of group objects within a tab, used to categorize pages under a common heading.
group	String	The display name for a collapsible section of pages.
pages	Array	An array of strings, where each string is a path to a Markdown file (without the .mdx or .md extension).

Sources: docs.json:12-73

Below is a code snippet from docs.json showing the configuration for the "Guides" tab.

{
  "tab": "Guides",
  "groups": [
    {
      "group": "Getting started",
      "pages": [
        "index",
        "quickstart",
        "development"
      ]
    },
    {
      "group": "Customization",
      "pages": [
        "essentials/settings",
        "essentials/navigation"
      ]
    }
  ]
}

Sources: docs.json:13-30

Content and File Organization

Each entry in the pages array within docs.json corresponds to a Markdown file (.mdx or .md). The string value is the file path relative to the root directory, excluding the file extension. For example, the page quickstart refers to the file quickstart.mdx.

• quickstart -> quickstart.mdx
• essentials/navigation -> essentials/navigation.mdx

This structure keeps the content decoupled from the navigation configuration, allowing writers to focus on the Markdown files while the overall site structure is managed centrally.

Sources: docs.json:20-22, docs.json:28-29, quickstart.mdx, development.mdx

Development and Preview

To create and preview guide pages, the Mintlify CLI provides a local development environment. This allows you to see your changes in real-time before publishing.

Sources: README.md:13-23

Development Workflow

The process involves installing the CLI, running the local server, and viewing the documentation in a browser.

The following flowchart shows the steps to set up and run the local development environment.

Key Commands

Command	Description
npm i -g mint	Installs the Mintlify CLI globally.
mint dev	Starts the local development server from the folder containing docs.json.
mint update	Updates the CLI to the most recent version, used for troubleshooting.

Sources: README.md:16, README.md:21, README.md:28

Relationship with API Reference Pages

While this document focuses on Guide pages, it's important to understand how they relate to other documentation types, such as API references. In docs.json, both are defined as top-level tabs, but their content sources can differ.

• Guide Pages: Content is sourced from individual Markdown files referenced in the pages array.
• API Reference Pages: Can be sourced from an OpenAPI specification file, such as api-reference/openapi.json. The navigation in docs.json may point to introductory pages, but the detailed endpoint documentation is generated from the OpenAPI schema.

This separation allows for narrative, instructional content (Guides) to coexist with structured, auto-generated technical references (API Reference).

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