Skip to main content

Docs Vite To Docusaurus 中文适配 Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将现有 Docusaurus 文档站改造成以中文为默认语言、页面结构与 docs-vite/docs 完全一致的新版本开发者文档站，并保留必要的旧链接兼容。

Architecture: docs-vite/docs 作为唯一正文来源，docs/ 重建为中文主内容树，docusaurus.config.ts 与 sidebars.ts 同步切换为中文默认站点和新版导航结构。旧的 Guide / Configuration 等淘汰页面不再保留正文，通过 redirect 兼容历史路径。

Tech Stack: Docusaurus 3.9、TypeScript、Markdown/MDX、pnpm

File Structure​

Content files to create​

  • docs/widget/index.md
  • docs/widget/examples.md
  • docs/chat-page/index.md
  • docs/chat-page/webview-appbridge.md
  • docs/webhooks/index.md
  • docs/api/index.md
  • docs/api/chat/index.md

Content files to rewrite from docs-vite/docs​

  • docs/index.md
  • docs/widget/installation.md
  • docs/widget/javascript-api.md
  • docs/chat-page/direct-link.md
  • docs/chat-page/self-hosted.md
  • docs/chat-page/parameters.md
  • docs/webhooks/setup.md
  • docs/webhooks/signature.md
  • docs/webhooks/events.md
  • docs/webhooks/payload.md
  • docs/api/authentication.md
  • docs/api/error-codes.md
  • docs/api/chat/create-session.md
  • docs/api/chat/create-session-batch.md
  • docs/api/chat/create-group.md
  • docs/api/chat/delete-session.md
  • docs/api/chat/dissolve-group.md
  • docs/api/chat/dissolve-group-batch.md

Config files to modify​

  • docusaurus.config.ts
  • sidebars.ts

Legacy files to delete after migration​

  • docs/widget/README.md
  • docs/widget/configuration.md
  • docs/widget/_category_.json
  • docs/chat-page/README.md
  • docs/chat-page/_category_.json
  • docs/webhooks/README.md
  • docs/webhooks/_category_.json
  • docs/api/README.md
  • docs/api/_category_.json
  • docs/api/chat/README.md
  • docs/api/chat/_category_.json
  • docs/guide/README.md
  • docs/guide/quickstart.md
  • docs/guide/_category_.json

Translation folders to leave untouched in this phase​

  • i18n/zh-CN/**
  • i18n/zh-TW/**

Reason: first-pass migration only changes the default Chinese source; legacy translation directories should not be used as the active source of truth, but they do not need destructive cleanup unless they block builds.

Chunk 1: Rebuild The Markdown Content Tree​

Task 1: Snapshot the page inventory before edits​

Files:

  • Modify: none

  • Reference: docs-vite/docs/**/*.md

  • Reference: docs/**/*.md

  • Step 1: Record the source page list

Run:

find docs-vite/docs -type f -name '*.md' | sort

Expected: 25 Markdown files from docs-vite/docs, including widget/examples.md and chat-page/webview-appbridge.md.

  • Step 2: Record the current Docusaurus page list

Run:

find docs -type f -name '*.md' | sort

Expected: existing Docusaurus Markdown tree still contains guide/*, README.md landing pages, and does not yet contain the new index.md landing pages.

  • Step 3: Save the migration map in the working notes

Use this mapping as the source of truth during implementation:

docs-vite/docs/index.md                         -> docs/index.md
docs-vite/docs/widget/index.md                  -> docs/widget/index.md
docs-vite/docs/widget/installation.md           -> docs/widget/installation.md
docs-vite/docs/widget/javascript-api.md         -> docs/widget/javascript-api.md
docs-vite/docs/widget/examples.md               -> docs/widget/examples.md
docs-vite/docs/chat-page/index.md               -> docs/chat-page/index.md
docs-vite/docs/chat-page/direct-link.md         -> docs/chat-page/direct-link.md
docs-vite/docs/chat-page/self-hosted.md         -> docs/chat-page/self-hosted.md
docs-vite/docs/chat-page/parameters.md          -> docs/chat-page/parameters.md
docs-vite/docs/chat-page/webview-appbridge.md   -> docs/chat-page/webview-appbridge.md
docs-vite/docs/webhooks/index.md                -> docs/webhooks/index.md
docs-vite/docs/webhooks/setup.md                -> docs/webhooks/setup.md
docs-vite/docs/webhooks/signature.md            -> docs/webhooks/signature.md
docs-vite/docs/webhooks/events.md               -> docs/webhooks/events.md
docs-vite/docs/webhooks/payload.md              -> docs/webhooks/payload.md
docs-vite/docs/api/index.md                     -> docs/api/index.md
docs-vite/docs/api/authentication.md            -> docs/api/authentication.md
docs-vite/docs/api/error-codes.md               -> docs/api/error-codes.md
docs-vite/docs/api/chat/index.md                -> docs/api/chat/index.md
docs-vite/docs/api/chat/create-session.md       -> docs/api/chat/create-session.md
docs-vite/docs/api/chat/create-session-batch.md -> docs/api/chat/create-session-batch.md
docs-vite/docs/api/chat/create-group.md         -> docs/api/chat/create-group.md
docs-vite/docs/api/chat/delete-session.md       -> docs/api/chat/delete-session.md
docs-vite/docs/api/chat/dissolve-group.md       -> docs/api/chat/dissolve-group.md
docs-vite/docs/api/chat/dissolve-group-batch.md -> docs/api/chat/dissolve-group-batch.md

Task 2: Migrate the home page and widget section​

Files:

  • Modify: docs/index.md

  • Create: docs/widget/index.md

  • Modify: docs/widget/installation.md

  • Modify: docs/widget/javascript-api.md

  • Create: docs/widget/examples.md

  • Delete later: docs/widget/README.md

  • Delete later: docs/widget/configuration.md

  • Delete later: docs/widget/_category_.json

  • Step 1: Replace the site home page with the docs-vite version

Copy the body of docs-vite/docs/index.md into docs/index.md. Preserve a root slug in frontmatter so the page remains /.

Recommended frontmatter:

---
title: TWT Chat 开发者文档
slug: /
---
  • Step 2: Create the widget landing page

Create docs/widget/index.md from docs-vite/docs/widget/index.md.

Recommended frontmatter:

---
title: 网站小部件
slug: /widget/
---
  • Step 3: Rewrite widget detail pages

Replace docs/widget/installation.md and docs/widget/javascript-api.md with the corresponding docs-vite content. Normalize any internal links so they point to Docusaurus routes like ./installation, ./javascript-api, and ../chat-page/parameters.

  • Step 4: Create the new examples page

Create docs/widget/examples.md from docs-vite/docs/widget/examples.md. Preserve all code examples and the security warning about APP_SECRET.

  • Step 5: Run a focused content diff check

Run:

diff -u docs-vite/docs/widget/index.md docs/widget/index.md || true
diff -u docs-vite/docs/widget/examples.md docs/widget/examples.md || true

Expected: only intentional Docusaurus-specific frontmatter or link-format differences.

  • Step 6: Commit the widget migration chunk

Run:

git add docs/index.md docs/widget
git commit -m "docs: migrate home and widget docs to docs-vite structure"

Task 3: Migrate the chat-page and webhooks sections​

Files:

  • Create: docs/chat-page/index.md

  • Modify: docs/chat-page/direct-link.md

  • Modify: docs/chat-page/self-hosted.md

  • Modify: docs/chat-page/parameters.md

  • Create: docs/chat-page/webview-appbridge.md

  • Delete later: docs/chat-page/README.md

  • Delete later: docs/chat-page/_category_.json

  • Create: docs/webhooks/index.md

  • Modify: docs/webhooks/setup.md

  • Modify: docs/webhooks/signature.md

  • Modify: docs/webhooks/events.md

  • Modify: docs/webhooks/payload.md

  • Delete later: docs/webhooks/README.md

  • Delete later: docs/webhooks/_category_.json

  • Step 1: Create the chat-page landing page

Create docs/chat-page/index.md from docs-vite/docs/chat-page/index.md.

Recommended frontmatter:

---
title: 聊天页面
slug: /chat-page/
---
  • Step 2: Rewrite chat-page detail pages

Replace docs/chat-page/direct-link.md, docs/chat-page/self-hosted.md, and docs/chat-page/parameters.md from the docs-vite sources, keeping all tables, examples, and notes.

  • Step 3: Create the WebView AppBridge page

Create docs/chat-page/webview-appbridge.md from docs-vite/docs/chat-page/webview-appbridge.md. Keep all Flutter, JavaScript bridge, and permission sections intact.

  • Step 4: Create the webhooks landing page and rewrite its detail pages

Create docs/webhooks/index.md from docs-vite/docs/webhooks/index.md, then replace setup.md, signature.md, events.md, and payload.md with the docs-vite versions.

Recommended frontmatter:

---
title: Webhooks
slug: /webhooks/
---
  • Step 5: Run a focused internal-link scan

Run:

rg -n "guide/|configuration|README" docs/chat-page docs/webhooks

Expected: no remaining links to retired guide/*, widget/configuration, or section README.md pages.

  • Step 6: Commit the chat-page and webhooks migration chunk

Run:

git add docs/chat-page docs/webhooks
git commit -m "docs: migrate chat-page and webhook docs to docs-vite structure"

Task 4: Migrate the API section​

Files:

  • Create: docs/api/index.md

  • Modify: docs/api/authentication.md

  • Modify: docs/api/error-codes.md

  • Delete later: docs/api/README.md

  • Delete later: docs/api/_category_.json

  • Create: docs/api/chat/index.md

  • Modify: docs/api/chat/create-session.md

  • Modify: docs/api/chat/create-session-batch.md

  • Modify: docs/api/chat/create-group.md

  • Modify: docs/api/chat/delete-session.md

  • Modify: docs/api/chat/dissolve-group.md

  • Modify: docs/api/chat/dissolve-group-batch.md

  • Delete later: docs/api/chat/README.md

  • Delete later: docs/api/chat/_category_.json

  • Step 1: Create the API landing pages

Create both landing pages from docs-vite:

docs/api/index.md
docs/api/chat/index.md

Recommended frontmatter:

---
title: 开放 API
slug: /api/
---

and

---
title: 在线聊天
slug: /api/chat/
---
  • Step 2: Rewrite the API detail pages

Replace docs/api/authentication.md, docs/api/error-codes.md, and every file under docs/api/chat/ with the matching docs-vite content. Preserve request/response examples and error tables exactly unless Docusaurus link syntax requires a small edit.

  • Step 3: Verify API page coverage

Run:

find docs-vite/docs/api -type f -name '*.md' | sed 's#docs-vite/docs/##' | sort
find docs/api -type f -name '*.md' | sed 's#docs/##' | sort

Expected: the second list contains every API Markdown path from the first list, adapted under docs/.

  • Step 4: Commit the API migration chunk

Run:

git add docs/api
git commit -m "docs: migrate api docs to docs-vite structure"

Chunk 2: Reconfigure Docusaurus For Chinese-First Routing​

Task 5: Rewrite the manual sidebar to match docs-vite​

Files:

  • Modify: sidebars.ts

  • Step 1: Replace the existing English-first sidebar structure

Rewrite sidebars.ts so it points at the new Chinese landing pages and matches the docs-vite ordering exactly.

Target structure:

const sidebars: SidebarsConfig = {
  docsSidebar: [
    { type: "doc", id: "index" },
    {
      type: "category",
      label: "网站小部件",
      link: { type: "doc", id: "widget/index" },
      items: ["widget/installation", "widget/javascript-api", "widget/examples"],
    },
    {
      type: "category",
      label: "聊天页面",
      link: { type: "doc", id: "chat-page/index" },
      items: [
        "chat-page/direct-link",
        "chat-page/self-hosted",
        "chat-page/parameters",
        "chat-page/webview-appbridge",
      ],
    },
    {
      type: "category",
      label: "Webhooks",
      link: { type: "doc", id: "webhooks/index" },
      items: ["webhooks/setup", "webhooks/signature", "webhooks/events", "webhooks/payload"],
    },
    {
      type: "category",
      label: "开放 API",
      link: { type: "doc", id: "api/index" },
      items: [
        "api/authentication",
        {
          type: "category",
          label: "在线聊天",
          link: { type: "doc", id: "api/chat/index" },
          items: [
            "api/chat/create-session",
            "api/chat/create-session-batch",
            "api/chat/create-group",
            "api/chat/delete-session",
            "api/chat/dissolve-group",
            "api/chat/dissolve-group-batch",
          ],
        },
        "api/error-codes",
      ],
    },
  ],
};
  • Step 2: Verify that no retired doc ids remain

Run:

rg -n "guide/|README|configuration" sidebars.ts

Expected: no matches.

Task 6: Switch the site configuration to Chinese-first and add redirects​

Files:

  • Modify: docusaurus.config.ts

  • Step 1: Change the site metadata to Chinese

Update:

  • title -> TWT Chat 开发者文档

  • tagline -> concise Chinese description

  • navbar labels -> Chinese

  • footer labels -> Chinese

  • Step 2: Change the locale strategy

Set Docusaurus to a Chinese-only default locale for this phase:

i18n: {
  defaultLocale: "zh-CN",
  locales: ["zh-CN"],
  localeConfigs: {
    "zh-CN": {
      label: "简体中文",
      htmlLang: "zh-CN",
    },
  },
},

Also remove:

  • localeDropdown

  • the nonDefaultLocalePathPattern logic

  • any English-default redirect assumptions

  • Step 3: Add legacy redirect coverage

Replace the current redirect setup with explicit legacy redirects for removed pages and old locale-prefixed paths.

Recommended structure:

plugins: [
  [
    "@docusaurus/plugin-client-redirects",
    {
      redirects: [
        { to: "/", from: ["/en", "/en/", "/zh-CN", "/zh-CN/"] },
        {
          to: "/",
          from: [
            "/guide",
            "/guide/",
            "/guide/README",
            "/guide/quickstart",
            "/zh-CN/guide",
            "/zh-CN/guide/quickstart",
            "/en/guide/quickstart",
          ],
        },
        {
          to: "/widget/javascript-api",
          from: [
            "/widget/configuration",
            "/zh-CN/widget/configuration",
            "/en/widget/configuration",
          ],
        },
      ],
    },
  ],
],

If implementation testing shows /widget/examples is the closer replacement for widget/configuration, switch the redirect target before finalizing.

  • Step 4: Verify no stale locale UI remains

Run:

rg -n "localeDropdown|English|Guide|Getting Started" docusaurus.config.ts

Expected: no stale English-first navigation text remains.

  • Step 5: Commit the configuration chunk

Run:

git add sidebars.ts docusaurus.config.ts
git commit -m "docs: switch docusaurus config to chinese docs-vite navigation"

Chunk 3: Remove Legacy Content And Verify The Site​

Task 7: Delete retired files and confirm the new tree is canonical​

Files:

  • Delete: docs/widget/README.md

  • Delete: docs/widget/configuration.md

  • Delete: docs/widget/_category_.json

  • Delete: docs/chat-page/README.md

  • Delete: docs/chat-page/_category_.json

  • Delete: docs/webhooks/README.md

  • Delete: docs/webhooks/_category_.json

  • Delete: docs/api/README.md

  • Delete: docs/api/_category_.json

  • Delete: docs/api/chat/README.md

  • Delete: docs/api/chat/_category_.json

  • Delete: docs/guide/README.md

  • Delete: docs/guide/quickstart.md

  • Delete: docs/guide/_category_.json

  • Step 1: Delete retired content files

Run:

rm docs/widget/README.md docs/widget/configuration.md docs/widget/_category_.json
rm docs/chat-page/README.md docs/chat-page/_category_.json
rm docs/webhooks/README.md docs/webhooks/_category_.json
rm docs/api/README.md docs/api/_category_.json
rm docs/api/chat/README.md docs/api/chat/_category_.json
rm docs/guide/README.md docs/guide/quickstart.md docs/guide/_category_.json
  • Step 2: Verify the canonical docs tree

Run:

find docs -type f \\( -name '*.md' -o -name '_category_.json' \\) | sort

Expected: the tree contains the new index.md landing pages and no longer contains guide/*, README.md, or _category_.json files for retired sections.

  • Step 3: Commit the cleanup chunk

Run:

git add docs
git commit -m "docs: remove retired docs pages after docs-vite migration"

Task 8: Run full validation and manual smoke checks​

Files:

  • Test: docs/**

  • Test: sidebars.ts

  • Test: docusaurus.config.ts

  • Step 1: Run link-oriented static checks

Run:

rg -n "guide/|widget/configuration|README" docs sidebars.ts docusaurus.config.ts

Expected: no remaining references to retired pages, aside from redirect definitions that intentionally preserve old routes.

  • Step 2: Run the Docusaurus build

Run:

pnpm build

Expected: PASS with no broken links and no broken markdown links.

  • Step 3: Smoke-check the critical routes in the built output

Run:

find dist -maxdepth 3 -type f | rg "/(index|widget|chat-page|webhooks|api).*\\.html$"

Expected: built HTML exists for:

  • /index.html

  • /widget/index.html

  • /widget/examples.html

  • /chat-page/index.html

  • /chat-page/webview-appbridge.html

  • /webhooks/index.html

  • /api/index.html

  • /api/chat/index.html

  • Step 4: Manually verify redirect targets in the browser

Start a local server:

pnpm serve

Then manually open:

  • /chat/guide/quickstart
  • /chat/widget/configuration
  • /chat/zh-CN

Expected: each route lands on the configured replacement page instead of 404.

  • Step 5: Final commit

Run:

git add docs sidebars.ts docusaurus.config.ts
git commit -m "docs: complete docs-vite chinese migration plan"

Notes For The Follow-Up zh-TW / en Phase​

  • Do not translate from old i18n content. Use the new Chinese docs/ tree as the source.
  • Re-enable multi-locale config only after the Chinese route structure is stable and validated.
  • Generate zh-TW and en on the same path topology: /widget/, /chat-page/, /webhooks/, /api/, /api/chat/.