公開ドキュメントのナビゲーションとサイドバーをカスタマイズする

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: 外部 URL にジャンプするためのナビゲーション エントリの外部 URL (例: "https://apigit.com")。
  • 子供たち: ネストされたエントリを含む配列。サブメニューとネストされたサイドバーを有効にします。
  • グループ (トップレベルのみ): 2 レベルのトップ ナビゲーション メニューのエントリを含む配列。

エントリには主に 4 つの種類があります。

  • { 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 仕様ファイルとマークダウン ドキュメントがサイド バー ツリーとしてアルファベット順にリストされます。次のようになります。 APIGIT MockServer powered by expressjs and node