Skip to content

feat(docs): add PackageManagerTabs and register it globally #433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
allxsmith merged 4 commits into from
Aug 1, 2026
Merged

feat(docs): add PackageManagerTabs and register it globally #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
23c9989
feat(docs): add PackageManagerTabs and register it globally
allxsmith Jul 30, 2026
5b0d3e6
fix(docs): harden PackageManagerTabs and document how to author it
allxsmith Aug 1, 2026
a0935ce
refactor(docs): author PackageManagerTabs as children, drop the flatt…
allxsmith Aug 1, 2026
1883de3
fix(docs): correct the frozen-install translation and reject leaked f…
allxsmith Aug 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 43 additions & 7 deletions docs/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,13 +24,23 @@ The build runs `docusaurus-plugin-llms` (configured in `docusaurus.config.js`),
- `/llms.txt` (curated index) and `/llms-full.txt` (full concatenation)
- a per-page `.md` twin for every doc page (so `llms.txt` links resolve)

The plugin reads **source** markdown and has no transform hook, so MDX tab JSX would land
verbatim in those artifacts. `scripts/flatten-llms-tabs.mjs` runs after `docusaurus build`
(chained in the `build` script — it can't be a plugin, since core runs every `postBuild` under
`Promise.all`) and flattens it: `<PackageManagerTabs command="…" />` collapses to the pnpm
command, `<Tabs>` linearizes to `####` headings keeping every `TabItem` body. It never touches
code — fenced _or_ inline — because `docs/api/components/tabs.md` documents bestax-bulma's own
`<Tabs.List>`/`<Tabs.Item>`. Covered by `scripts/flatten-llms-tabs.test.mjs` (`pnpm test`).
The plugin reads **source** markdown, and since 0.5.0 it strips PascalCase JSX tags while
keeping their **inner text**. That single rule decides how components must be authored if their
content is to reach an agent:

- **Content in children survives.** A fenced code block wrapped in a component comes out the
other side as exactly that fence, wrapper gone. This is why `<PackageManagerTabs>` takes a
pnpm fence as its children rather than a `command` prop — the artifact is then correct by
construction, with no build step to keep in sync.
- **Content in props does not.** It goes with the tag, silently. A self-closing
`<PackageManagerTabs command="…" />` left an empty section in every artifact while the
rendered site looked fine. Before giving a docs component a prop that carries prose or a
command, check what the generated `.md` looks like.

The known casualty is `<TabItem label="…">`: the label is Docusaurus's own prop and can't move
to children, so `<Tabs>` collapses to its bodies with nothing marking which option is which.
`skills/theming.mdx` and `skills/custom-component.mdx` are affected. Tracked upstream at
rachfop/docusaurus-plugin-llms#64, which asks for a preserve-list or a pre-clean hook.

`build` then chains `scripts/strip-generated-markers.mjs`, which removes the
`<!-- bestax:generated -->` markers from the built `.md`/`.txt` only — the plugin does not
Expand Down Expand Up @@ -71,4 +81,30 @@ it, so a novel non-standard `package.json` key and extra release churn weren't w
space children with `m*`/`p*`.
- Code examples must compile against the current library API; when a component changes, its
docs page changes in the same PR (CONTRIBUTING requires docs before approval).
- **Install and run commands go in `<PackageManagerTabs>`**, wrapping the pnpm fence you would
have written anyway, so npm/yarn/bun readers don't translate by hand:

````md
<PackageManagerTabs>

```bash
pnpm create bestax@latest my-app
cd my-app
pnpm install
```

</PackageManagerTabs>
````

Registered globally in `src/theme/MDXComponents.js` — no import. Write the **pnpm** form
exactly, one command per line; npm, yarn and bun are derived from it, and a line that isn't a
pnpm verb (`cd my-app`, a `#` comment) passes through unchanged. Blank lines around the fence
are required — without them MDX treats it as literal text, not a code block. The component
derives the command back out of the fence and throws during the prerender if the round trip
isn't exact, so a non-canonical fence (`npm install foo`, odd spacing) fails the build rather
than rendering three tabs derived from something the page never showed.

- **`.md` files here render JSX**, because `markdown.format` defaults to `mdx` and
`docusaurus.config.js` does not override it. That is load-bearing but easy to miss: setting
`format: 'detect'` would make every `.md` page render its tags as literal text.
- Markdown is prettier-formatted (`pnpm format:check` covers `md`/`mdx`).
4 changes: 4 additions & 0 deletions docs/docs/guides/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,14 @@ That's it! Visit http://localhost:5173 to see your app. Skip ahead to [Next Step

### Install Dependencies

<PackageManagerTabs>

```bash
pnpm add @allxsmith/bestax-bulma
```

</PackageManagerTabs>

### Add Bestax CSS

Import the combined stylesheet in your application entry point (e.g. `main.jsx`, `main.tsx`, `index.js`):
Expand Down
2 changes: 1 addition & 1 deletion docs/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"docusaurus": "docusaurus",
"docs": "docusaurus start",
"start": "docusaurus start",
"build": "docusaurus build && node scripts/flatten-llms-tabs.mjs && node scripts/strip-generated-markers.mjs",
"build": "docusaurus build && node scripts/strip-generated-markers.mjs",

@coderabbitai coderabbitai Bot Aug 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Preserve labels for standard tabs in LLM artifacts.

Line 9 removes the only tab-flattening stage. docs/CLAUDE.md states that generated Markdown loses <TabItem> labels and identifies affected pages. The published LLM artifacts will contain tab bodies without their option names.

Keep a generic tab-label preservation step, or replace it before removing flatten-llms-tabs.mjs. PackageManagerTabs children solve this component’s command output only.

As per coding guidelines, “Keep documentation and the published LLM index accurate when documentation changes affect them.”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/package.json` at line 9, Update the docs build script while preserving a
generic tab-label transformation for standard Docusaurus tabs before generating
published LLM artifacts. Do not rely solely on PackageManagerTabs; retain or
replace the functionality previously provided by flatten-llms-tabs.mjs so
affected Markdown includes each tab’s option label.

Source: Coding guidelines

"test": "node --test \"scripts/*.test.mjs\"",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
Expand Down
77 changes: 0 additions & 77 deletions docs/scripts/flatten-llms-corpus.test.mjs
View file
Open in desktop

This file was deleted.

150 changes: 0 additions & 150 deletions docs/scripts/flatten-llms-gate.test.mjs
View file
Open in desktop

This file was deleted.

Loading
Loading