docs: overhaul the documentation structure and content

.pre-commit-config.yaml

@@ -1,3 +1,6 @@
+# Standalone examples vendor frontend assets and serve as teaching material; skip all hooks.
+exclude: ^website/public/examples/
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: "v5.0.0"

README.md

@@ -9,7 +9,7 @@
 
 <p><strong>Build your Bub.</strong></p>
 
-[Website](https://bub.build) · [Docs](https://bub.build/docs/getting-started/) · [Hub](https://hub.bub.build)
+[Website](https://bub.build) · [Docs](https://bub.build/docs/) · [Hub](https://hub.bub.build)
 
 </div>
 
@@ -25,9 +25,9 @@ In a Python 3.12+ project:
 uv add bub
 ```
 
-Run your first agent with the [SDK guide](https://bub.build/docs/build/sdk/), then [serve it with FastAPI](https://bub.build/docs/tutorials/fastapi/) when you need an HTTP endpoint.
+Run your first agent with the [SDK guide](https://bub.build/docs/sdk/), then [serve it with FastAPI](https://bub.build/docs/sdk/web-service/) when you need an HTTP endpoint.
 
-You can also embed `BubAgent` to reuse the application's settings and plugin hooks in your service. This uses `bub[app]`; [Reuse application plugins](https://bub.build/docs/build/reuse-plugins/) explains the integration choices and their requirements.
+You can also embed `BubAgent` to reuse the application's settings and plugin hooks in your service. This uses `bub[app]`; [Reuse application plugins](https://bub.build/docs/sdk/reuse-plugins/) explains the integration choices and their requirements.
 
 ## Customize the Bub app
 
@@ -51,11 +51,11 @@ Follow the prompts to choose plugins and configure your model, then start a conv
 bub chat
 ```
 
-[Run your first conversation](https://bub.build/docs/getting-started/first-turn/) walks through a task in your workspace. [Customize the Bub app](https://bub.build/docs/build/) covers tools, plugins, and packaging. For `uv tool install` and other setup options, see [Install Bub](https://bub.build/docs/getting-started/install/#app-install).
+[Run your first conversation](https://bub.build/docs/app/workspace/) walks through a task in your workspace. [Customize the Bub app](https://bub.build/docs/app/workspace/) covers tools, plugins, and packaging. For `uv tool install` and other setup options, see [Install Bub](https://bub.build/docs/getting-started/install/#app-install).
 
 ## Documentation
 
-- [Choose a starting point](https://bub.build/docs/getting-started/)
+- [Choose a starting point](https://bub.build/docs/)
 - [Shared concepts and capabilities](https://bub.build/docs/concepts/)
 - [API and application reference](https://bub.build/docs/reference/)
 

website/TRANSLATING.md

@@ -0,0 +1,34 @@
+# Translating the docs
+
+Applies to every locale under `src/content/docs/`. The English source is `src/content/docs/docs/`. Keep its paragraph and heading structure; do not merge, split, or reorder.
+
+## Glossary
+
+A term that names code keeps its spelling. Do not invent a local name. A new locale adds a column.
+
+Anything not listed is an ordinary technical word. Translate it the usual way; judge each case. Keep one rendering per page.
+
+| Term | zh-cn | Note |
+| --- | --- | --- |
+| `turn` | `turn` | One inbound message and all its work. Never 轮次, 回合. |
+| `tape` | `tape` | The conversation record. Never 磁带. |
+| `anchor` | `anchor` | Where the context starts. |
+| `handoff` | `handoff` | Writes a new anchor. |
+| `state` | `state` | The dictionary a turn shares. Type `TurnState`. |
+| `steering` | `steering` | Never 引导. |
+| `queue up` | `queue up` | Never 排队. |
+| `hook` | `hook` | Never 钩子. |
+| `envelope` | `envelope` | Never 信封. |
+| `trace` | `trace` | Never 轨迹, 追踪. |
+| `CodeMode` | `CodeMode` | The class. The feature is `code mode`. Never 代码模式. |
+| `extra` | `extra` | User-facing prose says "`app` extra" and "`trace` extra"; keep `extra` for the packaging mechanism, `--extra`, and `package[extra]`. |
+| `harness` | `harness` | The app layer around the loop. |
+
+Docs pages explain the `steering` and `queue up` difference where it changes the reader's choice. A steering message that the current turn does not consume falls back to the pending queue; pages that mention steering keep that fallback rule. For the general statement, link [Steering and queueing](https://docs.github.com/en/copilot/how-tos/copilot-sdk/features/steering-and-queueing) instead of translating it.
+
+## Punctuation (zh-cn)
+
+- Use full-width `，。；：！？、` and `「」`.
+- Put one space between Chinese and Latin letters, digits, or inline code.
+- Use `……` for an ellipsis and `——` for a dash.
+- Put no space next to full-width punctuation, and none inside bold or italic text.

website/astro.config.mjs

@@ -4,6 +4,7 @@ import { defineConfig, envField } from 'astro/config';
 import tailwindcss from '@tailwindcss/vite';
 import starlight from '@astrojs/starlight';
 import cloudflare from '@astrojs/cloudflare';
+import headingAnchors from './src/integrations/heading-anchors.mjs';
 import peleDiagrams from './src/integrations/pele.mjs';
 
 const astro_image_mode =
@@ -26,6 +27,10 @@ export default defineConfig({
     imageService: image_service,
     prerenderEnvironment: 'node',
   }),
+  redirects: {
+    '/docs/sdk/options': '/docs/sdk/tape',
+    '/zh-cn/docs/sdk/options': '/zh-cn/docs/sdk/tape',
+  },
   site: process.env.SITE_URL ?? 'https://bub.build',
   env: {
     schema: {
@@ -39,6 +44,13 @@ export default defineConfig({
     },
   },
   vite: {
+    // Keep the dependency cache of `astro build` away from the one `astro dev`
+    // uses. When both share `node_modules/.vite`, every build rewrites the
+    // optimized deps and a running dev server answers with "There is a new
+    // version of the pre-bundle" instead of hot-reloading.
+    cacheDir:
+      process.env.VITE_CACHE_DIR ??
+      (astro_image_mode === 'dev' ? 'node_modules/.vite' : 'node_modules/.vite-build'),
     plugins: [tailwindcss()],
     resolve: {
       alias: {
@@ -47,6 +59,8 @@ export default defineConfig({
     },
   },
   integrations: [
+    // Let headings carry an explicit id so every locale shares the same anchor.
+    headingAnchors(),
     // Transform Mermaid fences before Starlight highlights code blocks.
     peleDiagrams(),
     starlight({
@@ -111,104 +125,103 @@ export default defineConfig({
       social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/bubbuild/bub' }],
       sidebar: [
         {
-          label: 'Start here',
-          translations: { 'zh-CN': '从这里开始' },
-          items: ['docs/getting-started', 'docs/getting-started/install'],
+          label: 'Get started',
+          translations: { 'zh-CN': '开始' },
+          items: ['docs/getting-started', 'docs/getting-started/install', 'docs/getting-started/quickstart'],
         },
         {
-          label: 'Build your own agent',
-          translations: { 'zh-CN': '构建自己的 Agent' },
-          items: ['docs/build/sdk', 'docs/build/reuse-plugins', 'docs/tutorials/fastapi'],
+          label: 'Concepts',
+          translations: { 'zh-CN': '核心概念' },
+          items: [
+            'docs/concepts',
+            'docs/concepts/kernel',
+            'docs/concepts/turn',
+            'docs/concepts/tape',
+            'docs/concepts/events',
+            'docs/concepts/extension-points',
+          ],
         },
         {
-          label: 'Customize the Bub app',
-          translations: { 'zh-CN': '定制 Bub 应用' },
+          label: 'Use Bub App',
+          translations: { 'zh-CN': '使用 Bub 应用' },
           items: [
-            'docs/build',
-            'docs/getting-started/first-turn',
-            'docs/concepts/turn-pipeline',
             {
-              label: 'Extend the app',
-              translations: { 'zh-CN': '扩展应用' },
-              collapsed: true,
+              label: 'Run',
+              translations: { 'zh-CN': '运行' },
+              collapsed: false,
               items: [
-                'docs/build/app-tools',
-                'docs/getting-started/first-skill',
-                'docs/build/skills',
-                'docs/getting-started/first-plugin',
-                'docs/build/plugins',
-                'docs/build/hooks',
-                'docs/build/distribution',
+                'docs/app/workspace',
+                'docs/app/configure',
+                'docs/app/terminal',
+                'docs/app/gateway',
               ],
             },
             {
-              label: 'Configure and run',
-              translations: { 'zh-CN': '配置与运行' },
-              collapsed: true,
+              label: 'Extend',
+              translations: { 'zh-CN': '扩展' },
+              collapsed: false,
               items: [
-                'docs/operate',
-                'docs/operate/configure',
-                'docs/operate/channels',
-                'docs/operate/channels/cli',
-                'docs/operate/channels/telegram',
-                'docs/operate/deploy',
+                'docs/app/tools',
+                'docs/app/skills',
+                'docs/app/subagents',
+                'docs/app/plugins',
               ],
             },
             {
-              label: 'Integrations',
-              translations: { 'zh-CN': '接入集成' },
-              collapsed: true,
+              label: 'Distribute and deploy',
+              translations: { 'zh-CN': '分发与部署' },
+              collapsed: false,
               items: [
-                {
-                  slug: 'docs/tutorials',
-                  label: 'Integration index',
-                  translations: { 'zh-CN': '集成索引' },
-                },
-                'docs/tutorials/mcp',
-                'docs/tutorials/agent-plugins',
-                'docs/tutorials/language-extensions',
-                'docs/tutorials/acp-server',
-                'docs/tutorials/tapestore-sqlalchemy',
-                'docs/tutorials/observability',
-                'docs/tutorials/local-llama-cpp',
+                'docs/app/distribution',
+                'docs/app/deploy',
               ],
             },
           ],
         },
         {
-          label: 'Shared concepts and capabilities',
-          translations: { 'zh-CN': '公共概念与能力' },
+          label: 'Build your own Bub Agent',
+          translations: { 'zh-CN': '构建你的 Bub Agent' },
           items: [
-            'docs/concepts',
-            'docs/build/tools',
-            'docs/concepts/tape-and-context',
-            'docs/concepts/events',
-            'docs/concepts/surfaces',
-            'docs/concepts/philosophy',
+            'docs/sdk',
+            'docs/sdk/tools',
+            'docs/sdk/tape',
+            'docs/sdk/events',
+            'docs/sdk/web-service',
           ],
         },
         {
-          label: 'Reference',
-          translations: { 'zh-CN': '参考' },
+          label: 'Integrations',
+          translations: { 'zh-CN': '集成' },
           items: [
+            'docs/integrations/reuse-app',
+            'docs/integrations/mcp',
             {
-              slug: 'docs/reference',
-              label: 'Agent and app APIs',
-              translations: { 'zh-CN': 'Agent 与应用接口' },
+              label: 'Portable Agent Plugins',
+              translations: { 'zh-CN': '使用 Agent Plugins' },
+              slug: 'docs/integrations/agent-plugins',
             },
-            {
-              label: 'Application reference',
-              translations: { 'zh-CN': '应用参考' },
-              items: [
-                'docs/reference/hooks',
-                'docs/reference/cli',
-                'docs/reference/settings',
-                'docs/reference/types',
-              ],
-            },
-            'docs/reference/versions',
+            'docs/integrations/acp',
+            'docs/integrations/local-models',
+            'docs/integrations/storage',
+            'docs/integrations/observability',
+          ],
+        },
+        {
+          label: 'Reference',
+          translations: { 'zh-CN': '参考' },
+          items: [
+            'docs/reference/cli',
+            'docs/reference/settings',
+            'docs/reference/tools',
+            'docs/reference/python-api',
+            'docs/reference/hooks',
           ],
         },
+        {
+          label: 'Migration',
+          translations: { 'zh-CN': '迁移' },
+          items: ['docs/migration/v0-6'],
+        },
       ],
     }),
   ],