docs(ia): audience-first navigation — Learn/Build/Operate/Extend sections + business-facing entry pages - #3423
Merged
Merged
Conversation
…ions + business-facing entry pages - Root sidebar split into four audience sections via separators (zero URL churn) - getting-started split into Start Here / Cheatsheets; CLI and Validating Metadata moved to Deployment & Operations with redirects (incl. chain fix for the pre-2026-07 guides redirect) and in-content link rewrites - New: getting-started/platform-capabilities (business-language capability tour, HotCRM as running example) and getting-started/build-without-code (Studio/Console/Setup visual-building guide) - concepts/index gains Find Your Path reader cards; ui section renamed 'Views & Apps' in nav and home cards Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The cn language was declared in docs.site.json and mapped in middleware, but lib/i18n.ts (what fumadocs actually consumes) only ever listed en and there is zero cn content — a config-vs-runtime drift that made the site look bilingual. Remove the declaration and the dead zh->cn Accept-Language mapping; keep the i18n plumbing so a future language is content + one config line. Verified: docs build passes; with Accept-Language: zh-CN, /docs serves the English page with no /cn redirect. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Feedback pass on the audience-first IA: the sidebar still read as crowded. - Drop the hardcoded Docs/Blog links above the tree (layout.shared.tsx) - Strip per-item icons from all 14 section meta.json files (text-only tree) - Merge the one-item Operate section: Learn / Build / Platform - Take References and Releases (lookup content, 22 generated/log pages) out of the tree — URLs still resolve (verified 200) and the docs home page links both; getting-started no longer defaultOpen so the first screen shows all twelve top-level entries at once Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
'What Can It Do?' and 'Build Without Code' were buried inside the Get Started folder — the exact audience they serve would never expand it. Promote both to top-level Learn entries (/docs/platform-capabilities, /docs/build-without-code; new-in-this-PR pages, so no redirects needed), and lead the docs-home 'Start here' list with them. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
'What Can It Do?' grows from one page into a Learn-section folder of ten business-language pages — data, views, forms & quality, automation, approvals, permissions, analytics, AI, integrations & everyday work, and a requirements one-pager template. Each page keeps three anchors: business scenarios, an 'In HotCRM' pointer at the running example, and a 'For developers' cross-link into the technical Build docs. The index becomes a card directory; new pages drop hand-written H1s (frontmatter title renders them). URL /docs/platform-capabilities → /docs/capabilities (page introduced in this PR, so no redirect debt). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… src/flows) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The page moved getting-started → deployment in this PR; its single pre-existing occurrence (a table header) moves with it. Net change zero. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
os-zhuang
pushed a commit
that referenced
this pull request
Jul 29, 2026
…tore, first docs sweep Three related closures on the just-merged v17 release page (#3906): 1. The Console section was missing 25 objectui commits. The v17 frontend window is cf2d56e32a11 → 4a4829d0ef39 = 128 commits, but the pending console-*.md changesets covered only 103: the range 2cb8d78e24ad...c6cfdf1288b6 landed with no changeset — exactly the "SHA bump leaves no trace" failure scripts/bump-objectui.sh exists to prevent. Two of the missing commits are breaking and each is the frontend half of a backend change the page already documented (useClientNotifications delegates ↔ #3612 SDK removal; @object-ui/types Capabilities re-exports ↔ the retired capabilities cluster). Both now sit beside their backend halves and in the upgrade checklist, with the other eight substantive commits folded into the Console section and .changeset/console-c6cfdf1288b6-backfill.md recording the range itself. 2. "releases" returns to the root sidebar. #3423 unlisted References and Releases together ("lookup content ... the docs home page links both"); that trade holds for References (22 generated pages) but not for Releases in a release window, when the upgrade notes are what people open the docs for. References stays out. check-release-notes now enforces what its success line already claimed: the section must be reachable via the root nav OR a /docs/releases link on the docs home — either satisfies it (preserving #3423's option), losing both fails the build. Negative-tested both directions. 3. First v17 docs sweep (docs/v17-docs-sweep.md — playbook + append-only run log with a watermark, built to re-run while the RC train iterates). Run 1 fixed the drift v17 left in hand-written prose: services-checklist (17→16 services, graphql rows, the dissolved ObjectStackProtocol), the anonymous-deny matrix still listing /graphql + handleGraphQL, sharing docs describing owner/group shapes as "declared but not enforced" (they no longer parse), http-protocol claiming enable.trash exists, REST/GraphQL in objectql diagrams/prose, and the objectstack-api skill description (mirrors regenerated via gen:skill-docs). False positives and out-of-scope findings (spec comment drift, implementation-status.mdx staleness) are logged for the next run. Verified: pnpm docs:build passes; check:release-notes / doc-authoring / role-word / org-identifier / nul-bytes / skill-docs-sync all green; the new guard branch fails when both entry points are removed and passes with either. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXvaYR7TiJBCxYwjn51owH
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.
Why
The docs site reads developer-only: 14 top-level sections in one flat sidebar (155+ pages), contributor content (kernel/protocol/plugins) at the same level as user content, cheatsheets crowding getting-started, and no entry point at all for evaluators or visual-tool builders — even though Studio/Console is half the product. Follow-up to the 2026-07 module-based IA migration, this pass answers "who is reading?".
What
Navigation (config-only, zero URL churn)
Two tooling pages rehomed (the only moves)
getting-started/cli→deployment/cli,getting-started/validating-metadata→deployment/validating-metadataguides/validating-metadataredirect retargeted to avoid a chain; all in-content links rewritten (12 files)New audience pages
getting-started/platform-capabilities— business-language capability tour (data, views, automation, approvals, permissions, analytics, AI, integrations) with HotCRM as the clickable running examplegetting-started/build-without-code— what admins/analysts do in Console, Studio (4 pillars, draft→publish, same validation gate), Setup, and Marketplaceconcepts/indexgains Find Your Path cards routing four reader personasVerification
pnpm --filter @objectstack/docs buildpasses/en/docs/getting-started/cli308s to/docs/deployment/cliOut of scope / follow-ups
cnlanguage is enabled in config but has zero content — needs a product decision (fill Learn-section first vs. disable the toggle)🤖 Generated with Claude Code