自定义导航和侧边栏以发布文档

APIGit

2025-03-12

当您从 git 存储库的特定提交(SHA)发布 API 规范和 Markdown 文档以生成文档站点时,您可能需要:

  • 定义文档站点的布局,包括顶部导航菜单和侧边栏。
  • 指定哪些文件应该可以在已发布的文档站点上访问。

这些定制可以通过添加apigit.json文件到你的存储库。这是一个简单示例:

{
	"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"
		}
	]
}

下面是一个截图,展示了根据提供的内容最终导航和侧边栏的显示方式apigit.json 例子: APIGIT MockServer powered by expressjs and node

导航文件(apigit.json)

导航条目的结构

所有导航条目均在nav数组中的apigit.json文件。以下是每个条目可用字段的说明:

  • 姓名 (必需的):导航或侧边栏条目的显示名称。
  • 蛞蝓 (选修的):条目的 URL 友好标识符。如果省略,将根据名称自动生成。
  • 文件:存储库中特定文档或 API 规范的文件路径。
  • 网址:导航入口的外部url(例如:“https://apigit.com”),将导致跳转到外部url。
  • 孩子们:包含嵌套条目的数组,启用子菜单和嵌套侧边栏。
  • 团体 (仅限顶层):包含两级顶部导航菜单条目的数组。

主要有四种类型的条目:

  • { name, slug, file }
  • { name, slug, url }
  • { name, slug, children }
  • { name, slug, group } (仅限顶级导航)

创建导航文件

要创建导航文件:

  1. 单击“+”图标。
  2. 导航到“导航(apigit.json)”选项卡。
  3. 单击“创建”按钮。

这将自动生成apigit.json根据存储库当前的文件层次结构创建文件。然后,您可以进一步自定义此初始结构。

Create Navigation file

编辑导航文件

要编辑现有的导航文件:

  1. 选择apigit.json来自您的存储库的文件。
  2. 直接在我们的内置编辑器中编辑导航条目。

编辑器顶部有一个有用的按钮,可以自动生成导航结构,类似于初始创建过程,为进一步的编辑提供了方便的起点。

Create Navigation file

无需导航(apigit.json)

当根文件夹中没有 apigit.json 时,当您发布 api 文档时,我们将按字母顺序将 api 规范文件和 markdown 文档列为侧边栏树。它看起来像这样。 APIGIT MockServer powered by expressjs and node