Personalizza la navigazione e la barra laterale per pubblicare documenti
APIGit
2025-03-12
Quando pubblichi specifiche API e documenti Markdown da un commit specifico (SHA) di un repository git per generare il tuo sito di documentazione, potresti voler:
- Definire il layout del sito di documentazione, incluso un menu di navigazione superiore e barre laterali.
- Specificare quali file devono essere accessibili sul sito della documentazione pubblicata.
Queste personalizzazioni possono essere ottenute aggiungendo unapigit.jsonfile nel tuo repository. Ecco un esempio minimo:
{
"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"
}
]
}
Di seguito è riportato uno screenshot che illustra come potrebbero apparire la navigazione finale e la barra laterale in base a quanto fornitoapigit.json esempio:
File di navigazione (apigit.json)
Struttura delle voci di navigazione
Tutte le voci di navigazione sono definite all'interno delnavschiera nelapigit.jsonfile. Ecco una spiegazione dei campi disponibili per ogni voce:
- nome (necessario): Nome visualizzato della voce di navigazione o della barra laterale.
- lumaca (opzionale): Un identificatore URL-friendly per la voce. Se omesso, verrà generato automaticamente in base al nome.
- file: Percorso del file per raggiungere il documento specifico o la specifica API nel tuo repository.
- url: L'URL esterno (ad esempio: "https://apigit.com") della voce di navigazione, che porterà a un URL esterno.
- bambini: Un array contenente voci nidificate, che abilita sottomenu e barre laterali nidificate.
- gruppo (solo livello superiore): Un array contenente voci per un menu di navigazione superiore a due livelli.
Esistono principalmente quattro tipi di voci:
{ name, slug, file }{ name, slug, url }{ name, slug, children }{ name, slug, group }(solo navigazione di primo livello)
Creazione di un file di navigazione
Per creare un file di navigazione:
- Fare clic sull'icona "+".
- Passare alla scheda "Navigazione (apigit.json)".
- Fare clic sul pulsante "Crea".
Ciò genera automaticamente una struttura iniziale per l'apigit.jsonfile in base alla gerarchia di file corrente del tuo repository. Puoi quindi personalizzare ulteriormente questa struttura iniziale.
Modifica del file di navigazione
Per modificare un file di navigazione esistente:
- Selezionare il
apigit.jsonfile dal tuo repository. - Modifica le voci di navigazione direttamente tramite il nostro editor integrato.
L'editor include un utile pulsante nella parte superiore che può generare automaticamente la struttura di navigazione, simile al processo di creazione iniziale, fornendo un comodo punto di partenza per ulteriori modifiche.
senza navigazione (apigit.json)
quando non c'è apigit.json nella cartella principale, quando pubblichi documenti API, elencheremo i file di specifiche API e i documenti markdown nel loro ordine alfabetico come un albero della barra laterale. Ecco come appare.
© 2024 APIGit Inc.