Skip to content

[docs] Add CodeToggle widget; use it for install snippets#8101

Open
dokson wants to merge 1 commit into
palantir:developfrom
dokson:ac/docs-install-snippet
Open

[docs] Add CodeToggle widget; use it for install snippets#8101
dokson wants to merge 1 commit into
palantir:developfrom
dokson:ac/docs-install-snippet

Conversation

@dokson
Copy link
Copy Markdown

@dokson dokson commented May 4, 2026

Summary

Fixes #7684.

Adds a tabbed code-snippet toggle to the docs and uses it for the install commands on the Blueprint and Getting Started pages, so a reader can pick their package manager (npm / yarn / pnpm) instead of the docs hard-coding one.

Architecture

The widget is split in two:

  • @blueprintjs/docs-theme<CodeToggle> — generic, reusable. Takes tabs: { id, label, code }[], an id for the underlying <Tabs>, and an optional storageKey for cross-page persistence in localStorage. Uses Blueprint <Tabs>, <Pre>, <Code>. Sits next to the existing CodeExample widget so any consumer of the docs theme can reuse it.
  • docs-app<InstallSnippet> — thin wrapper that supplies the npm/yarn/pnpm install commands for @blueprintjs/core react react-dom, registered as a @reactDocs InstallSnippet Documentalist tag.

Why the split: Documentalist's @reactDocs tag does not accept arguments, so each specific use case needs its own thin wrapper component registered in tags/reactDocs.ts. The generic CodeToggle lives in docs-theme where it's reusable.

Extensibility

  • New package manager (e.g. bun): one entry in the TABS array in installSnippet.tsx. Tab order is the array order.
  • New snippet toggle elsewhere (e.g. Vite vs Webpack vs Parcel): a new thin wrapper that calls <CodeToggle tabs={...} id="..." />, re-exported via tags/reactDocs.ts, then @reactDocs MyNewWidget in the relevant MDX page.

Persistence

InstallSnippet passes storageKey="bp-docs-pm-preference", so the reader's PM choice is remembered across pages and across visits. Default is pnpm (the docs current default after #7685). The state hydrates from localStorage after mount to avoid first-render mismatches and stays SSR-safe.

Test plan

  • eslint clean on changed files
  • prettier applied
  • pnpm --filter @blueprintjs/docs-theme run compile:esm clean
  • Bundle docs-app and inspect the rendered widget in the browser (deferred — local Windows env hits an unrelated docs-data:compile issue with Node 25; the repo's .nvmrc pins 24.14.1)

No new tests: neither docs-theme nor docs-app has a test setup today, and adding the infrastructure for a single widget felt like scope creep for this issue. Happy to follow up in a separate PR if maintainers want test coverage for docs-theme widgets.

Add CodeToggle to @blueprintjs/docs-theme: a generic tabbed code-snippet
widget that takes any number of { id, label, code } tabs and optionally
persists the user's selection in localStorage. Sits alongside CodeExample
in the published docs theme, so other consumers of @blueprintjs/docs-theme
can reuse it for their own snippet toggles.

In docs-app, register a thin InstallSnippet wrapper that supplies the
npm/yarn/pnpm install commands for @blueprintjs/core and use it on the
Blueprint and Getting Started pages via the @reactdocs Documentalist tag.

Adding another package manager (e.g. bun) is one entry in TABS in
installSnippet.tsx. Adding a different snippet toggle elsewhere is a new
thin wrapper that calls CodeToggle with its own tabs.

Fixes palantir#7684.
@changelog-app
Copy link
Copy Markdown

changelog-app Bot commented May 4, 2026

Generate changelog in packages/docs-theme/changelog/@unreleased

Type (Select exactly one)

  • Feature (Adding new functionality)
  • Improvement (Improving existing functionality)
  • Fix (Fixing an issue with existing functionality)
  • Break (Creating a new major version by breaking public APIs)
  • Deprecation (Removing functionality in a non-breaking way)
  • Migration (Automatically moving data/functionality to a new system)

Description

[docs] Add CodeToggle widget; use it for install snippets

Check the box to generate changelog(s)

  • Generate changelog entry

@dokson
Copy link
Copy Markdown
Author

dokson commented May 4, 2026

@mm-wang — implements the toggle from #7684 as a reusable CodeToggle widget in @blueprintjs/docs-theme. The Blueprint and Getting Started pages now use it for the install command. See PR description for the architectural choices and how to extend (more package managers, or a different toggle for some other code section). Feedback welcome.

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.

[Docs] Add code snippet toggle

1 participant