Documentation

ドキュメント開発ガイド

概要

idp-serverのドキュメントはDocusaurusで構築。日英対応。

• 公開URL: https://hirokazu-kobayashi-koba-hiro.github.io/idp-server/
• フレームワーク: Docusaurus 3.x

ディレクトリ構造

documentation/
├── docs/                           # メインコンテンツ
│   ├── content_01_intro/          # イントロダクション
│   ├── content_02_quickstart/     # クイックスタート
│   ├── content_03_concepts/       # コンセプト・設計思想
│   ├── content_04_protocols/      # プロトコル仕様
│   ├── content_05_how-to/         # 設定・構築ガイド
│   ├── content_06_developer-guide/ # 開発者ガイド
│   ├── content_07_reference/      # リファレンス
│   ├── content_08_ops/            # 運用・デプロイ
│   ├── content_09_project/        # プロジェクト情報
│   ├── content_10_ai_developer/   # AI開発者向け詳細リファレンス
│   ├── content_11_learning/       # 学習コンテンツ・チュートリアル
│   ├── content_20_testing/        # テスト関連
│   ├── document-index.md          # ドキュメントガイド（読者別）
│   └── introduction.md            # はじめに
│
├── openapi/                        # OpenAPI仕様書
│   ├── control-plane/             # 管理API仕様
│   └── application-plane/         # OAuth/OIDC API仕様
│
├── architecture/                   # アーキテクチャ図
├── blog/                          # ブログ記事
├── src/                           # Docusaurusカスタムコンポーネント
├── static/                        # 静的ファイル（画像等）
├── docusaurus.config.js           # Docusaurus設定
├── sidebars.js                    # サイドバー設定
└── package.json

コンテンツカテゴリ

ローカルプレビュー

起動

cd documentation
npm install
npm run start

日本語版

npm run start -- --locale ja

ビルド

npm run build

ドキュメント作成

ファイル命名規則

{カテゴリ}-{連番}-{説明}.md

例:
- quickstart-01-getting-started.md
- concept-02-multi-tenant.md
- developer-03-token-endpoint.md

Front Matter

---
sidebar_position: 1
title: ページタイトル
description: ページの説明（SEO用）
---

# 見出し

本文...

サイドバー順序

sidebar_position で順序を制御:

---
sidebar_position: 1  # 1番目に表示
---

開発者ガイド構造

content_06_developer-guide/
├── 01-getting-started/            # 開発環境構築
├── 02-control-plane/              # 管理API実装ガイド
├── 03-application-plane/          # OAuth/OIDC実装ガイド
├── 04-implementation-guides/      # 機能別実装ガイド
├── 05-configuration/              # 設定ガイド
├── 06-patterns/                   # 共通実装パターン
├── 07-troubleshooting/            # トラブルシューティング
├── 08-reference/                  # リファレンス
└── learning-paths/                # 学習パス
    ├── 01-beginner.md
    ├── 02-control-plane-track.md
    ├── 03-application-plane-track.md
    └── 04-full-stack-track.md

AI開発者向けドキュメント

content_10_ai_developer/ はClaude Code向けの詳細リファレンス:

OpenAPI仕様書

openapi/
├── control-plane/
│   ├── organization-api.yaml      # 組織管理API
│   ├── tenant-api.yaml            # テナント管理API
│   ├── client-api.yaml            # クライアント管理API
│   └── user-api.yaml              # ユーザー管理API
│
└── application-plane/
    ├── oauth-api.yaml             # OAuth 2.0 API
    ├── oidc-api.yaml              # OpenID Connect API
    └── ciba-api.yaml              # CIBA API

OpenAPI編集

# Lint
npx @redocly/cli lint openapi/control-plane/organization-api.yaml

# プレビュー
npx @redocly/cli preview-docs openapi/control-plane/organization-api.yaml

多言語対応

ディレクトリ構造

documentation/
├── docs/                  # デフォルト（英語）
└── i18n/
    └── ja/
        └── docusaurus-plugin-content-docs/
            └── current/   # 日本語版

翻訳追加

# 翻訳ファイル生成
npm run write-translations -- --locale ja

コマンド一覧

# 開発サーバー起動
npm run start

# 日本語版
npm run start -- --locale ja

# ビルド
npm run build

# ビルド結果プレビュー
npm run serve

# 翻訳ファイル生成
npm run write-translations -- --locale ja

# OpenAPI Lint
npx @redocly/cli lint openapi/**/*.yaml

よく編集するファイル

関連スキル