メインコンテンツまでスキップ

ドキュメント運用

siteはwebsite/配下のDocusaurus 3で構築し、通常のPRでbetaへ変更します。

手書きと自動生成を分ける​

範囲Source扱い
はじめに、Guide、Architecture、Contributing、Migrationwebsite/docs/手書き。日本語をdefaultとする
Tool referenceServer/src/services/tools/generatorから生成
Resource catalogServer/src/services/resources/generatorから生成

自動生成referenceはtools/generate_docs_reference.pyが所有します。tool名、parameter名、type、descriptionなど実装と同期すべき内容を手で分岐させません。

<!-- examples:start -->と<!-- examples:end -->の間だけは手書きexampleとして再生成後も保持されます。

日本語をdefaultにする​

docusaurus.config.jsでは次を基本契約とします。

  • defaultLocale: 'ja'
  • 日本語URLはlocale prefixなし: /getting-started, /failuresなど
  • 英語は/en/配下
  • defaultの手書きdocsは日本語
  • 英語版を維持するpageはwebsite/i18n/en/docusaurus-plugin-content-docs/current/へ置く

API名、tool名、config key、code、exact error string、generated referenceなど技術的なcanonical identifierは原文を保持します。

手書きpageを変更する​

  1. website/docs/の対象fileを編集する
  2. local preview:
cd website
npm run start
  1. http://localhost:3000/unity-mcp/で確認する
  2. beta向けPRを作る

CIはnpm run buildを実行し、broken linkやlocale build failureを検出します。

新しいpageを追加する​

---
id: my-page
slug: /guides/my-page
title: ページタイトル
sidebar_label: 短い表示名
description: 検索・OG向けの説明
---

website/sidebars.jsへ追加します。URL slugにはproduct名を埋め込まず、意味のある一般的なpathを使います。

URLを変更する​

外部linkを壊さないようredirectを追加します。

{
  redirects: [
    { from: '/old/slug', to: '/new/slug' },
  ],
}

referenceを再生成する​

cd Server
uv run python ../tools/generate_docs_reference.py
git diff ../website/docs/reference

registry変更時はgenerated referenceも同じPRへ含めます。CIのdocs-generate.ymlがdriftを検出します。

Release note​

website/docs/releases.mdなど自動同期対象はgenerator / sync scriptを正本とし、生成bodyを手で翻訳して次回syncで上書きされる構造にしません。release本文が英語の場合も、navbar・sidebar・周辺説明は日本語defaultとします。

deploy​

betaへのpushからGitHub Pagesへdeployします。

公開先:

https://kafka2306.github.io/unity-mcp/

GitHub PagesのsourceはGitHub Actionsです。workflowは.github/workflows/docs-deploy.ymlを正本とします。

local searchは@easyops-cn/docusaurus-search-localを使用します。検索対象には日本語本文とexact technical stringの両方を残し、エラー原文からも到達できるようにします。