Personnaliser la navigation et la barre latérale pour publier des documents
APIGit
2025-03-12
Lorsque vous publiez des spécifications d'API et des documents Markdown à partir d'un commit spécifique (SHA) d'un référentiel git pour générer votre site de documentation, vous souhaiterez peut-être :
- Définissez la mise en page du site de documentation, y compris un menu de navigation supérieur et des barres latérales.
- Spécifiez quels fichiers doivent être accessibles sur le site de documentation publié.
Ces personnalisations peuvent être réalisées en ajoutant unapigit.jsondans votre dépôt. Voici un exemple simple :
{
"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"
}
]
}
Vous trouverez ci-dessous une capture d'écran illustrant à quoi pourraient ressembler la navigation finale et la barre latérale en fonction des informations fournies.apigit.json exemple:
Fichier de navigation (apigit.json)
Structure des entrées de navigation
Toutes les entrées de navigation sont définies dans lenavtableau dans leapigit.jsonfichier. Voici une explication des champs disponibles pour chaque entrée :
- nom (requis): Le nom d'affichage de l'entrée de navigation ou de barre latérale.
- limace (facultatif): Identifiant URL convivial pour l'entrée. S'il est omis, il sera automatiquement généré à partir du nom.
- déposer: Le chemin d'accès au fichier vers le document spécifique ou la spécification API dans votre référentiel.
- URL: L'URL externe (exemple : « https://apigit.com ») de l'entrée naviation, qui mènera à un saut vers une URL externe.
- enfants:Un tableau contenant des entrées imbriquées, permettant des sous-menus et des barres latérales imbriquées.
- groupe (niveau supérieur uniquement):Un tableau contenant des entrées pour un menu de navigation supérieur à deux niveaux.
Il existe principalement quatre types d’entrées :
{ name, slug, file }{ name, slug, url }{ name, slug, children }{ name, slug, group }(navigation de niveau supérieur uniquement)
Création d'un fichier de navigation
Pour créer un fichier de navigation :
- Cliquez sur l'icône « + ».
- Accédez à l'onglet « Navigation (apigit.json) ».
- Cliquez sur le bouton « Créer ».
Cela génère automatiquement une structure initiale pour leapigit.jsonfichier basé sur la hiérarchie actuelle de votre dépôt. Vous pouvez ensuite personnaliser davantage cette structure initiale.
Modification du fichier de navigation
Pour modifier un fichier de navigation existant :
- Sélectionnez le
apigit.jsonfichier de votre référentiel. - Modifiez les entrées de navigation directement dans notre éditeur intégré.
L'éditeur comprend un bouton utile en haut qui peut générer automatiquement la structure de navigation, similaire au processus de création initial, offrant un point de départ pratique pour des modifications ultérieures.
sans navigation (apigit.json)
Lorsqu'il n'y a pas de fichier apigit.json dans le dossier racine, lorsque vous publiez des documents API, nous listons les fichiers de spécifications API et les documents Markdown dans leur ordre alphabétique sous forme d'arborescence latérale. Voici à quoi cela ressemble.
© 2024 APIGit Inc.