Personaliza la navegación y la barra lateral para publicar documentos
APIGit
2025-03-12
Cuando publica especificaciones de API y documentos Markdown desde una confirmación específica (SHA) de un repositorio git para generar su sitio de documentación, es posible que desee:
- Definir el diseño del sitio de documentación, incluido un menú de navegación superior y barras laterales.
- Especifique qué archivos deben ser accesibles en el sitio de documentación publicada.
Estas personalizaciones se pueden lograr agregando unapigit.jsonArchivo a tu repositorio. Aquí tienes un ejemplo mínimo:
{
"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"
}
]
}
A continuación se muestra una captura de pantalla que ilustra cómo podrían aparecer la navegación final y la barra lateral según la información proporcionada.apigit.json ejemplo:
Archivo de navegación (apigit.json)
Estructura de las entradas de navegación
Todas las entradas de navegación se definen dentro delnavmatriz en elapigit.jsonarchivo. A continuación, se explican los campos disponibles para cada entrada:
- nombre (requerido):El nombre para mostrar de la entrada de navegación o de la barra lateral.
- babosa *(opcional)*Un identificador URL para la entrada. Si se omite, se generará automáticamente a partir del nombre.
- archivo:La ruta del archivo al documento específico o la especificación de API en su repositorio.
- URL:La URL externa (ejemplo: "https://apigit.com") de la entrada de navegación, que llevará a saltar a una URL externa.
- niños:Una matriz que contiene entradas anidadas, que habilita submenús y barras laterales anidadas.
- grupo (sólo nivel superior):Una matriz que contiene entradas para un menú de navegación superior de dos niveles.
Existen principalmente cuatro tipos de entradas:
{ name, slug, file }{ name, slug, url }{ name, slug, children }{ name, slug, group }(sólo navegación de nivel superior)
Creación de un archivo de navegación
Para crear un archivo de navegación:
- Haga clic en el icono "+".
- Vaya a la pestaña "Navegación (apigit.json)".
- Haga clic en el botón "Crear".
Esto genera automáticamente una estructura inicial para elapigit.jsonarchivo basado en la jerarquía de archivos actual de su repositorio. Puede personalizar aún más esta estructura inicial.
Edición del archivo de navegación
Para editar un archivo de navegación existente:
- Seleccione el
apigit.jsonarchivo de su repositorio. - Edite las entradas de navegación directamente dentro de nuestro editor integrado.
El editor incluye un botón útil en la parte superior que puede generar automáticamente la estructura de navegación, similar al proceso de creación inicial, proporcionando un punto de partida conveniente para futuras ediciones.
sin navegación (apigit.json)
Si no hay apigit.json en la carpeta raíz, al publicar documentos de la API, listaremos los archivos de especificaciones de la API y los documentos Markdown en orden alfabético como un árbol de barra lateral. Así es como se ve.
© 2024 APIGit Inc.