自訂導覽和側邊欄以發布文檔

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