Repository navigation
Conversation
100gle
changed the title
100gle
force-pushed
the
optimize-docs
branch
3 times, most recently
from
October 25, 2026 14:16
1df541b to
9cd00ac
Compare
Navigation now follows how you use Bub instead of which files exist: Get started -> Concepts -> Use Bub App -> Build your own Bub Agent -> Integrations -> Reference. The application comes first because the SDK track ends by reusing it through BubAgent. - move 31 pages per locale into app/, sdk/, and integrations/ - merge the two app hubs into a single "Use the Bub app" overview - merge the first-skill and first-plugin tutorials into the Skills and Plugins guides, keeping their prose - badge integration pages with App, Both, or Experimental - add 32 redirects for the old URLs in both locales - rewrite 336 internal links plus the README and landing-page links Only four pages have edited prose: the three merged pages and the Get started index, whose two sections are swapped. The other 68 page files are byte-identical after normalizing their internal URLs.
The group used to open on a choice between two paths, and then on the install page. It now reads: what Bub is, how to install it, how to run it once. - add "What is Bub?" as the first page: the loop, the two layers, the two ways to use it, three design rules, and an index of the rest of the documentation - move the old index page to quickstart/ so the group is linear instead of a hub - show the application install before the library install - redirect /docs to the introduction - rename the group label to "开始" in Chinese
The group used to hold six pages with titles that described the work
("Shared concepts and capabilities", "Where to add your code") instead
of the thing itself. Readers could not tell from the sidebar what each
page covered.
- merge the overview and the design page: one page now covers the four
concepts, the three layers, the terms, and the reasons behind them
- name the remaining pages Turn, Tape, Events, and Extension points,
matching bub.turn, bub.core.tape, bub.core.events, and the extension
table
- rename "Pipeline" to "Turn": process_inbound returns TurnResult, so a
turn is the concept and the pipeline is only how the app handles one
- state the turn/run/step distinction, which the pages used loosely
- say why hooks are not a core concept: the kernel reads no plugin hooks
- redirect /docs/concepts/design/ to the overview
- rewrite the prose in short sentences, one instruction per sentence
The section had two groups, "Run it" and "Extend it", that mixed
running, extending, and shipping. Pages were named after the work
("Configure the app", "Change application behavior") instead of the
thing they describe.
- group the pages into Run, Extend, and Ship
- name each page after its subject: Workspace, Configuration, Terminal,
Channels, Tools, Hooks, Distribution
- drop the app overview: the sidebar already lists every page
- merge the Telegram page into Channels, which covers it as one section
- rename first-session to workspace and remove the parts that quickstart
already explains
- fold the language-extension page into Plugins as "WASM plugins
(experimental)"; it described one plugin, not a concept of its own
- say what a channel covers, since a plugin can add another platform or
a background runtime
- use 技能 for skills, and keep Hooks and CodeMode in English because
the code uses those names
- add the Chinese redirects that were missing, and point 80 old URLs per
locale at their new pages
- keep the Vite dependency cache of build and dev apart, so a build no
longer forces a running dev server to reload its pre-bundle
The section used to put the whole SDK tour on one page, then follow it
with pages whose titles described the work ("Reusing plugins", "Agent
configuration") rather than what the reader gets. The first page was
called "First agent", which read like the opening of a tutorial series.
- open with Basic agent: one runnable example plus the stream it returns
- move the model, prompt, and parameter reference to Configure the agent
- rename app-plugins to reuse-plugins; the page is about reusing a
plugin, not about the app
- group the plugin page by what a plugin can do: add a tool, extend the
run (model and tool calls, then the other hooks), choose how to
connect, reuse BubAgent
- say that run_on() and run_once() take an open Tape object, not a tape
name, which run(tape=...) does
- give the run_stream() signature: session_id and prompt are required
- document the CodeMode name option
- say how several plugins share one hook: all of them run, a duplicate
tool, store, or tape context keeps the highest-priority provider, and
prompt sections join from low to high priority
- keep the redirect from /docs/sdk/app-plugins and /docs/build/*, so old
links still land
The section labeled every page with a surface badge, including the three
pages that work from either surface ("Both"), so the badge said nothing.
Page titles also described the reader's situation ("Run Bub with a local
llama.cpp model") instead of the thing being connected.
- drop the generic badges; keep App only on MCP, Agent Plugins, and ACP,
which need the application: a plugin install, the startup loader, or
`bub acp`
- name the pages after the connection: Connect an IDE over ACP, Use a
local llama.cpp model, Store conversation history in SQLite,
Observability
- restore the overview page and call it Overview / 概览, so the group has
a landing page again; its link text follows the new titles
- order the group from tools to packaging to editor to model to storage
to tracing
- drop the sidebar order fields the config already sets by position
Reference opened with an index whose top half pointed at /docs/sdk and /docs/concepts, and it listed a page called "Application types and lifecycle" that also documented streams and errors from the core loop. The 0.6 upgrade note sat among the lookup pages although it describes a one-off dependency change. - drop the reference index; the group starts at CLI and /docs/reference redirects there - merge the core and application interfaces into Python API, split into Core and Application sections - move the 0.6 upgrade note to its own Migration group as "Upgrade to 0.6.0", so the sidebar does not show a bare version number - drop the Application prefix from CLI, Settings, and Hooks - call the settings page 配置项 so it shares the 配置 root with the configuration guide instead of adding 设置 as a second term - keep /docs/reference/types and /docs/reference/versions redirecting to their new pages
A file name of 0.6 turns into no usable slug, and 0-6 reads like a range. The v prefix keeps the version recognisable and leaves room for v0-7.
The Chinese pages translated `turn` as 轮次, while `tape`, `hook`, `prompt`, and `envelope` stayed in English. A translated term breaks the link to `TurnState`, `TurnResult`, and `on_error(stage="turn")`, and 轮次 reads like a scheduling ordinal rather than a unit of work. Use `turn` in the prose instead, and define it once on the Turn page. Fold the same decision into the pages that leaned on 本轮 / 一轮 for the same concept, and keep 一轮 only where it means a CLI chat round or a `run`.
The restructure shipped the new tree together with a full 301 map for the old documentation URLs. Treat every old path as gone instead: the site is a single 0.x project with no obligation to keep pre-0.6 links alive. Point the remaining absolute links at the pages they describe so neither README nor the blog relies on a redirect: reuse-plugins, app/workspace, and app/hooks.
The sidebar is written out explicitly in `astro.config.mjs`, and Starlight only consults `sidebar.order` while sorting an autogenerated directory (`sortDirEntries` is reached from `groupFromDir`). Explicit `items` keep the array order, so the field has been dead weight on 46 pages. Keep the six frontmatter blocks that still carry a sidebar badge.
Cut the install page to the three paths that exist: CLI, SDK, source. Drop the virtual-environment section and move the PATH hint into an aside. Rewrite the migration note around the kernel/app dependency split, with tabs for the install methods, and mirror it in zh-cn.
Turn the core/app layer bullets and the four design principles into Card/CardGrid blocks so the page reads less flat, in both en and zh-cn.
Replace the tabbed layout with two standalone sections and render each walk as a Steps list. Sync the English page with the rewritten zh-cn one and use kbd for the Ctrl+C shortcut.
Starlight derives a heading id from its text, so a section had a different anchor in every locale: `## Storage` became `#storage` while a Chinese heading became a CJK slug. Cross-page links were written against one of them, and the other half silently pointed nowhere. Enable Satteri heading attributes and give the headings other pages link to an explicit id, so both locales share one anchor. This fixes the seventeen broken anchor links across the concepts, SDK, reference, app, and integration pages.
The concepts section introduced four ideas but never showed them working. The overview repeated the layers and principles from the introduction as prose instead of explaining how a message moves through the app, and the four topic pages read as flat prose piles with no diagrams and no emphasis. Rewrite each page around one question: - Overview: walk one message through a turn and the agent loop, then keep the layers, terms, and trade-offs that the other pages depend on. - Turn: explain why the stages exist, what crosses between them, and move the failure paths into an aside. - Tape: split the page along history versus context, which is the distinction everything else follows from, and add the handoff and fork diagrams. - Events: separate AgentEvent, StreamEvent, and TapeEntry up front, then derive observing, intercepting, and recording from that split. - Extension points: turn the link table into a decision page with questions to ask first and a rule for keeping one owner per job. Diagrams use the Mermaid pipeline the site already builds with Pele.
Drop narrative section banners and synonymous JSDoc while keeping non-obvious why comments around Starlight/Tailwind and theming.
Expand the English distribution page to match the polished Chinese version: distribution shapes, all-in-one wheel layout, Hatch configuration, build and publish steps, and a step-by-step pre-release verification checklist. Fix the pinned-workspace example: Bub has no BUB_WORKSPACE_PATH variable, so the sample now switches directory before calling bub_main() and documents that --workspace still wins. Reorder the sidebar so the distribution page precedes deployment.
Co-Authored-By: Kimi <noreply@anthropic.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A full pass over the docs: sections grouped by task, page titles named after what they cover, and the prose rewritten for plain, consistent wording. Old paths redirect to the new ones.
Draft for now — more edits are coming.