navigation of api documents
When you publish API specifications and Markdown documents from a specific commit (SHA) of a git repository to generate your documentation site, you might want to:
- Define the layout of the documentation site, including a top navigation menu and sidebars.
- Specify which files should be accessible on the published documentation site.
These customizations can be achieved by adding an apigit.json file to your repository. Here’s a minimal example:
{
"nav": [
{
"name": "Getting Started",
"slug": "getting-started",
"children": [
{
"name": "Introduction",
"slug": "introduction",
"file": "docs/introduction.md"
},
{
"name": "Installation Guide",
"slug": "installation-guide",
"file": "docs/installation.md"
}
]
},
{
"name": "Features",
"slug": "features",
"group": [
{
"name": "User Management",
"slug": "user-management",
"children": [
{
"name": "User Registration",
"slug": "user-registration",
"file": "features/user-management/registration.md"
},
{
"name": "User Authentication",
"slug": "user-authentication",
"file": "features/user-management/authentication.md"
},
{
"name": "Profile Settings",
"slug": "profile-settings",
"file": "features/user-management/profile-settings.md"
}
]
},
{
"name": "E-Commerce",
"slug": "e-commerce",
"children": [
{
"name": "Shopping Cart",
"slug": "shopping-cart",
"file": "features/e-commerce/shopping-cart.md"
},
{
"name": "Checkout Process",
"slug": "checkout-process",
"file": "features/e-commerce/checkout.md"
},
{
"name": "Order Tracking",
"slug": "order-tracking",
"file": "features/e-commerce/order-tracking.md"
}
]
},
{
"name": "Reporting & Analytics",
"slug": "reporting-analytics",
"children": [
{
"name": "Dashboard Overview",
"slug": "dashboard-overview",
"file": "features/reporting/dashboard-overview.md"
},
{
"name": "Sales Reports",
"slug": "sales-reports",
"file": "features/reporting/sales-reports.md"
},
{
"name": "User Activity Logs",
"slug": "user-activity-logs",
"file": "features/reporting/user-activity-logs.md"
}
]
}
]
},
{
"name": "API Reference",
"slug": "api-reference",
"children": [
{
"name": "Authentication",
"slug": "authentication",
"file": "api/authentication.json"
},
{
"name": "Users",
"slug": "users",
"children": [
{
"name": "Get User",
"slug": "get-user",
"file": "api/users/get-user.json"
},
{
"name": "Create User",
"slug": "create-user",
"file": "api/users/create-user.json"
}
]
},
{
"name": "Orders",
"slug": "orders",
"children": [
{
"name": "Place Order",
"slug": "place-order",
"file": "api/orders/place-order.json"
},
{
"name": "Cancel Order",
"slug": "cancel-order",
"file": "api/orders/cancel-order.json"
}
]
},
{
"name": "Github",
"slug": "github",
"url": "https://github.com/apigitlabs/apigit-support"
}
]
},
{
"name": "Guides",
"slug": "guides",
"children": [
{
"name": "Webhooks",
"slug": "webhooks",
"file": "guides/webhooks.md"
},
{
"name": "Rate Limits",
"slug": "rate-limits",
"file": "guides/rate-limits.md"
}
]
},
{
"name": "SDKs",
"slug": "sdks",
"children": [
{
"name": "JavaScript SDK",
"slug": "javascript-sdk",
"file": "sdk/javascript.md"
},
{
"name": "Python SDK",
"slug": "python-sdk",
"file": "sdk/python.md"
}
]
},
{
"name": "FAQ",
"slug": "faq",
"file": "docs/faq.md"
},
{
"name": "Changelog",
"slug": "changelog",
"file": "docs/changelog.md"
}
]
}Below is a screenshot illustrating how the final navigation and sidebar might appear based on the provided apigit.json example:
Navigation File (apigit.json)
Structure of Navigation Entries
All navigation entries are defined within the nav array in the apigit.json file. Here’s an explanation of the available fields for each entry:
- name (required): The display name of the navigation or sidebar entry.
- slug (optional): A URL-friendly identifier for the entry. If omitted, it will be automatically generated based on the name.
- file: The file path to the specific document or API specification in your repository.
- url: The external url (example:“https://apigit.com ”) of the naviation entry,which will lead to jump to an external url.
- children: An array containing nested entries, enabling submenus and nested sidebars.
- group (top-level only): An array containing entries for a two-level top navigation menu.
There are primarily four types of entries:
{ name, slug, file }{ name, slug, url }{ name, slug, children }{ name, slug, group }(top-level navigation only)
Creating a Navigation File
To create a navigation file:
- Click the ”+” icon.
- Navigate to the “Navigation (apigit.json)” tab.
- Click the “Create” button.
This automatically generates an initial structure for the apigit.json file based on your repository’s current file hierarchy. You can then customize this initial structure further.
Editing the Navigation File
To edit an existing navigation file:
- Select the
apigit.jsonfile from your repository. - Edit the navigation entries directly within our built-in editor.
The editor includes a helpful button at the top that can auto-generate the navigation structure, similar to the initial creation process, providing a convenient starting point for further edits.
without navigation (apigit.json)
when there is no apigit.json in the root folder, when you publish api documents, we will list out api spec files and markdown documents in its alpha order as a side bar tree. here is how it look like.
