Skip to content

docs: restructure top navigation around Learn vs Reference#9284

Merged
shulaoda merged 3 commits into
mainfrom
05-01-docs_restructure_top_navigation_around_learn_vs_reference
May 6, 2026
Merged

docs: restructure top navigation around Learn vs Reference#9284
shulaoda merged 3 commits into
mainfrom
05-01-docs_restructure_top_navigation_around_learn_vs_reference

Conversation

@shulaoda

@shulaoda shulaoda commented May 1, 2026

Copy link
Copy Markdown
Member

Summary

Restructures the docs site's top navigation so each top-level entry maps to a single user intent. The change is config-only: no markdown files are moved or renamed, no URLs change.

Why

Audited the current nav and found a few issues that hurt discoverability and intuition:

  1. The "Docs" dropdown is a redundant wrapper. Users had to click Docs → Guide to reach the entry-point doc; peer projects (Vite, Oxc) put Guide at the top level directly.
  2. "Options & APIs" conflates two different audiences. Options are user-facing config; APIs are programmatic surfaces — and the page it linked to (/reference/) is the auto-generated typedoc dictionary, which is distinct from the narrative API guide under /apis/.
  3. Built-in Plugins and the programmatic/plugin API guide were buried. Both were sub-sections inside the shared Guide sidebar (sidebarForUserGuide), invisible from the top nav. Plugin authors and integrators had to drill into Guide and scroll the sidebar to find them — a real discoverability gap given that plugins and programmatic API are core to Rolldown's value proposition.
  4. In-Depth was a separate sidebar context. Navigating from /guide/ to /in-depth/ swapped the entire sidebar, even though the two are a continuous learning path.

What changed

Top navigation

Before After
Docs (dropdown: Guide / In-Depth / Glossary) Guide
Options & APIs Reference
REPL Plugins
Resources (dropdown) API
REPL
Resources (dropdown)

The ordering follows the user journey from broad to specialized:

  • Guide — narrative learning path: Getting Started → In-Depth → Glossary
  • Reference — auto-generated dictionary of every option, function, interface, type
  • Plugins — Rolldown's built-in plugins (product docs)
  • API — programmatic usage: Bundler API, Plugin API (with sub-topics), CLI
  • REPL — external link
  • Resources — Team / Contribute / Roadmap

The Guide → Reference adjacency mirrors Vite and Rspack, where users learn the basics in Guide and then look up specific options in the second slot.

Sidebars

  • Guide absorbs In-Depth and Glossary as collapsed sections. Reading flows from /guide/getting-started through /in-depth/* to /glossary/* without losing sidebar context.
  • In-Depth ordering within the Guide sidebar: concept-style articles (Why Bundlers, Why Plugin Hook Filter, Module Types, External Modules, Directives) come first; feature deep-dives (code splitting, CJS bundling, TLA, DCE, lazy barrel, etc.) follow. The grouping is implicit through ordering, not split into separate sub-headers (avoids forcing users to identify "is this a concept or a feature?").
  • API, Plugins, and Reference each get their own sidebar so the route's surrounding context matches its top-nav identity.
  • The redundant Configuration Options → /reference entry inside the API sidebar is removed (Reference is now its own top-level entry).

Footer

The "Rolldown" footer column is updated to mirror the new top-nav (Guide · Reference · Plugins · API · Contribute · REPL).

What did NOT change

  • No markdown files moved or renamed.
  • All existing URLs (/guide/*, /in-depth/*, /glossary/*, /apis/*, /builtin-plugins/*, /reference/*) continue to resolve.
  • /reference/ content (auto-generated by typedoc) is untouched.
  • The Resources dropdown items (Team / Contribute / Roadmap) and their activeMatch patterns are unchanged.

@netlify

netlify Bot commented May 1, 2026

Copy link
Copy Markdown

Deploy Preview for rolldown-rs ready!

Name Link
🔨 Latest commit bb4ce71
🔍 Latest deploy log https://app.netlify.com/projects/rolldown-rs/deploys/69faaa9539a8a10007990f58
😎 Deploy Preview https://deploy-preview-9284--rolldown-rs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@shulaoda
shulaoda merged commit 2eae242 into main May 6, 2026
31 checks passed
@shulaoda
shulaoda deleted the 05-01-docs_restructure_top_navigation_around_learn_vs_reference branch May 6, 2026 04:36
@rolldown-guard rolldown-guard Bot mentioned this pull request May 7, 2026
@shulaoda shulaoda mentioned this pull request May 7, 2026
shulaoda added a commit that referenced this pull request May 7, 2026
## [1.0.0] - 2026-05-07

### 🐛 Bug Fixes

- dev/lazy: lazily compiled modules should be watched (#9301) by @h-a-n-a
- implement dynamic dominator merge logic (#9270) by @TheAlexLichter
- dev: apply __toCommonJS interop when CJS requires ESM in HMR finalizer (#9261) by @h-a-n-a

### 🚜 Refactor

- ecma_ast: tighten allocator access to enforce Sync invariant (#9278) by @IWANABETHATGUY
- scan_stage: remove stmt_infos field from EcmaView (#9276) by @IWANABETHATGUY
- link_stage: detach stmt_infos from EcmaView (#9274) by @IWANABETHATGUY
- link_stage: detach depended_runtime_helper from EcmaView to remove unsafe (#9265) by @IWANABETHATGUY
- link_stage: remove unsafe in determine_module_exports_kind (#9253) by @IWANABETHATGUY

### 📚 Documentation

- getting-started: remove RC warning for 1.0.0 release (#9310) by @shulaoda
- getting-started: update version references for 1.0.0 release (#9309) by @shulaoda
- add Vite+ tab to getting-started snippets (#9285) by @shulaoda
- lazy-barrel: clarify own-exports behavior for import-then-export records (#9298) by @shulaoda
- restructure top navigation around Learn vs Reference (#9284) by @shulaoda
- builtin-plugins: add bundle analyzer plugin docs (#9292) by @shulaoda
- design doc for reference_needed_symbols (#9264) by @IWANABETHATGUY

### ⚡ Performance

- devtools: write logs on a background thread (#9219) by @IWANABETHATGUY

### ⚙️ Miscellaneous Tasks

- mark esbuild/ts/parameter_props_use_define_for_class_fields_true as passed (#9308) by @sapphi-red
- deps: upgrade oxc to 0.129.0 (#9297) by @shulaoda
- deps: update rollup submodule for tests to v4.60.3 (#9294) by @sapphi-red
- deps: update test262 submodule for tests (#9295) by @sapphi-red
- ai: add rolldown REPL decode skill (#9245) by @Dunqing
pull Bot pushed a commit to olrtg/rolldown that referenced this pull request May 7, 2026
## [1.0.0] - 2026-05-07

### 🐛 Bug Fixes

- dev/lazy: lazily compiled modules should be watched (rolldown#9301) by @h-a-n-a
- implement dynamic dominator merge logic (rolldown#9270) by @TheAlexLichter
- dev: apply __toCommonJS interop when CJS requires ESM in HMR finalizer (rolldown#9261) by @h-a-n-a

### 🚜 Refactor

- ecma_ast: tighten allocator access to enforce Sync invariant (rolldown#9278) by @IWANABETHATGUY
- scan_stage: remove stmt_infos field from EcmaView (rolldown#9276) by @IWANABETHATGUY
- link_stage: detach stmt_infos from EcmaView (rolldown#9274) by @IWANABETHATGUY
- link_stage: detach depended_runtime_helper from EcmaView to remove unsafe (rolldown#9265) by @IWANABETHATGUY
- link_stage: remove unsafe in determine_module_exports_kind (rolldown#9253) by @IWANABETHATGUY

### 📚 Documentation

- getting-started: remove RC warning for 1.0.0 release (rolldown#9310) by @shulaoda
- getting-started: update version references for 1.0.0 release (rolldown#9309) by @shulaoda
- add Vite+ tab to getting-started snippets (rolldown#9285) by @shulaoda
- lazy-barrel: clarify own-exports behavior for import-then-export records (rolldown#9298) by @shulaoda
- restructure top navigation around Learn vs Reference (rolldown#9284) by @shulaoda
- builtin-plugins: add bundle analyzer plugin docs (rolldown#9292) by @shulaoda
- design doc for reference_needed_symbols (rolldown#9264) by @IWANABETHATGUY

### ⚡ Performance

- devtools: write logs on a background thread (rolldown#9219) by @IWANABETHATGUY

### ⚙️ Miscellaneous Tasks

- mark esbuild/ts/parameter_props_use_define_for_class_fields_true as passed (rolldown#9308) by @sapphi-red
- deps: upgrade oxc to 0.129.0 (rolldown#9297) by @shulaoda
- deps: update rollup submodule for tests to v4.60.3 (rolldown#9294) by @sapphi-red
- deps: update test262 submodule for tests (rolldown#9295) by @sapphi-red
- ai: add rolldown REPL decode skill (rolldown#9245) by @Dunqing

Co-authored-by: shulaoda <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants