Overview
When publishing API documentation from a Git repository, APIGIT extracts all API specifications and Markdown files from the specified commit (SHA) to build your documentation site. By default, files are displayed in the sidebar menu in their natural order, which may not provide the optimal user experience for your documentation.
To customize your documentation site’s navigation, menu structure, and layout, create an apigit.json file in your repository root. This navigation configuration file enables you to:
- Control which files are displayed or hidden
- Organize content into logical hierarchies
- Create custom navigation menus and layouts
- Add external links beyond repository files
- Enhance menu items with icons
The navigation configuration transforms your documentation from a simple file listing into a structured, user-friendly experience that helps readers find information quickly and efficiently.
Below is an example of how navigation and sidebar organization appears with a configured apigit.json file:
Configuration Example
Here’s a comprehensive example of an apigit.json configuration file:
{
"theme": "sequoia",
"nav": [
{
"name": "Getting Started",
"slug": "getting-started",
"icon": "sparkle",
"children": [
{
"name": "Introduction",
"slug": "introduction",
"file": "introduction.md",
"icon": "book-open"
}
]
},
{
"name": "Basic Elements",
"slug": "basic",
"icon": "swatch-book",
"children": [
{
"name": "Headers and Text",
"slug": "header-and-text",
"file": "basic/header-and-text.md",
"icon": "type"
},
{
"name": "Lists and Tables",
"slug": "list-and-tables",
"file": "basic/list-and-tables.md",
"icon": "table"
},
{
"name": "Icons",
"slug": "icon",
"file": "basic/icon.md",
"icon": "smile"
},
{
"name": "Admonitions",
"slug": "admonition",
"file": "basic/admonition.md",
"icon": "alert-triangle"
},
{
"name": "Code Blocks",
"slug": "code",
"file": "basic/code.md",
"icon": "code"
},
{
"name": "Images",
"slug": "image",
"file": "basic/image.md",
"icon": "image"
}
]
},
{
"name": "Interactive Components",
"slug": "components",
"icon": "component",
"children": [
{
"name": "Accordions",
"slug": "accordions",
"file": "components/accordions.md",
"icon": "chevron-down"
},
{
"name": "Expandable Content",
"slug": "expandable",
"file": "components/expandable.md",
"icon": "expand"
},
{
"name": "Cards",
"slug": "card",
"file": "components/card.md",
"icon": "square"
},
{
"name": "Card Groups",
"slug": "cardgroup",
"file": "components/cardgroup.md",
"icon": "layout-grid"
},
{
"name": "Code Groups",
"slug": "code-group",
"file": "components/code-group.md",
"icon": "file-code"
},
{
"name": "Columns",
"slug": "columns",
"file": "components/columns.md",
"icon": "layout-template"
},
{
"name": "Steps",
"slug": "steps",
"file": "components/steps.md",
"icon": "list-ordered"
},
{
"name": "Tabs",
"slug": "tabs",
"file": "components/tabs.md",
"icon": "folder-open"
},
{
"name": "Mathematical Formulas",
"slug": "formula",
"file": "components/formula.md",
"icon": "calculator"
},
{
"name": "Frames and Backgrounds",
"slug": "frame-and-background",
"file": "components/frame-and-background.md",
"icon": "picture-in-picture"
},
{
"name": "Video",
"slug": "video",
"file": "components/video.md",
"icon": "video"
},
{
"name": "Embedding",
"slug": "embedding",
"file": "components/embedding.md",
"icon": "external-link"
},
{
"name": "JSON Schema",
"slug": "json-schema",
"file": "components/json-schema.md",
"icon": "braces"
},
{
"name": "Fields",
"slug": "field",
"file": "components/Field.md",
"icon": "rectangle-ellipsis"
},
{
"name": "Tooltips",
"slug": "tooltips",
"file": "components/tooltips.md",
"icon": "help-circle"
},
{
"name": "Copy to Clipboard",
"slug": "copy-to-clipboard",
"file": "components/copy-to-clipboard.md",
"icon": "copy"
},
{
"name": "Change Tracking",
"slug": "change",
"file": "components/change.md",
"icon": "git-commit-horizontal"
}
]
},
{
"name": "Mermaid Diagrams",
"slug": "mermaid",
"icon": "swatch-book",
"children": [
{
"name": "Architecture Diagrams",
"slug": "architecture",
"file": "mermaid/architecture.md",
"icon": "building"
},
{
"name": "Class Diagrams",
"slug": "class",
"file": "mermaid/class.md",
"icon": "box"
},
{
"name": "Entity Relationship Diagrams",
"slug": "entity-relationship",
"file": "mermaid/entity-relationship.md",
"icon": "network"
},
{
"name": "Gantt Charts",
"slug": "gantt-chart",
"file": "mermaid/gantt-chart.md",
"icon": "calendar"
},
{
"name": "Git Graphs",
"slug": "git-graph",
"file": "mermaid/git-graph.md",
"icon": "git-branch"
},
{
"name": "Packet Diagrams",
"slug": "packet",
"file": "mermaid/packet.md",
"icon": "package"
},
{
"name": "Pie Charts",
"slug": "pie",
"file": "mermaid/pie.md",
"icon": "pie-chart"
},
{
"name": "Quadrant Charts",
"slug": "quadrant",
"file": "mermaid/quadrant.md",
"icon": "layout-grid"
},
{
"name": "Radar Charts",
"slug": "radar",
"file": "mermaid/radar.md",
"icon": "scan"
},
{
"name": "Requirement Diagrams",
"slug": "requirement",
"file": "mermaid/requirement.md",
"icon": "check-square"
},
{
"name": "Sequence Diagrams",
"slug": "sequence",
"file": "mermaid/sequence.md",
"icon": "arrow-right"
},
{
"name": "State Diagrams",
"slug": "state",
"file": "mermaid/state.md",
"icon": "circle-dot"
},
{
"name": "Timelines",
"slug": "timeline",
"file": "mermaid/timeline.md",
"icon": "clock"
},
{
"name": "Treemaps",
"slug": "treemap",
"file": "mermaid/treemap.md",
"icon": "tree-pine"
},
{
"name": "User Journey Maps",
"slug": "user-journey",
"file": "mermaid/user-journey.md",
"icon": "map"
},
{
"name": "XY Charts",
"slug": "xy",
"file": "mermaid/xy.md",
"icon": "line-chart"
}
]
}
]
}Navigation Configuration Reference
Entry Structure
All navigation entries are defined within the nav array in your apigit.json file. Each entry supports the following fields:
Required Fields:
- name: The display name for the navigation or sidebar entry
Optional Fields:
- slug: A URL-friendly identifier for the entry. If omitted, automatically generated from the name
- icon: Icon displayed before the name. Supports Lucide icons and Font Awesome icons
- file: File path to the document or API specification in your repository
- url: External URL for the navigation entry (e.g., “https://apigit.com ”)
- children: Array of nested entries for creating submenus and hierarchical navigation
- group: Array of entries for two-level top navigation menus (top-level only)
Entry Types
The navigation system supports four primary entry types:
- File Entry:
{ name, icon, slug, file }- Links to a document in your repository - External Link:
{ name, icon, slug, url }- Links to an external URL - Parent Entry:
{ name, icon, slug, children }- Contains nested navigation items - Group Entry:
{ name, icon, slug, group }- Creates grouped top-level navigation (top-level only)
Creating a Navigation File
To create a new navigation configuration:
- Click the ”+” icon in your project
- Navigate to the “Navigation (apigit.json)” tab
- Click the “Create” button
This automatically generates an initial apigit.json structure based on your repository’s current file hierarchy, which you can then customize to meet your specific documentation needs.
Editing Navigation Configuration
To modify an existing navigation file:
- Select the
apigit.jsonfile from your repository file list - Use the built-in editor to modify navigation entries
- Preview the navigation menu layout in real-time as you make changes
The editor includes an auto-generation button that recreates the navigation structure based on your current repository files, providing a convenient starting point for further customization.
Default Navigation Behavior
When no apigit.json file exists in your repository root, APIGIT automatically generates navigation by listing all API specification files and Markdown documents in alphabetical order as a sidebar tree. While functional, this default approach may not provide the optimal organization for your documentation.
For the best user experience, we recommend creating a custom navigation configuration that organizes your content logically and helps users find information efficiently.