From a71ae94fa735548156068eafe989fde2d9525968 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 18:58:07 +0000 Subject: [PATCH 1/3] =?UTF-8?q?docs(site):=20refresh=20write-guides=20page?= =?UTF-8?q?=20and=20align=20docs=20skill=20Di=C3=A1taxis=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The write-guides page had drifted from the docs skill and the current MDX pipeline: - Fix the tip aside's skill name (docs-guide → docs) - Replace the unsupported styles sidebar restriction with a StyleCase note, and fix the stale title field (actual field is sidebarLabel) - Document the satteriCodeFrame auto-wrap and title="..." fence meta - Reword the ServerCode caution against current behavior (still a bare pre) - Add the missing Demo component section with live examples - Move the canonical Diátaxis guidance (concept-first default + decision table) onto the page; the docs skill now defers to it Closes #1808 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Jk33yY4w5PkThQjkysDWgc --- .claude/skills/docs/SKILL.md | 13 +-- site/src/content/docs/how-to/write-guides.mdx | 110 ++++++++++++++++-- 2 files changed, 103 insertions(+), 20 deletions(-) diff --git a/.claude/skills/docs/SKILL.md b/.claude/skills/docs/SKILL.md index 3b7e98b70..78fa0663d 100644 --- a/.claude/skills/docs/SKILL.md +++ b/.claude/skills/docs/SKILL.md @@ -46,9 +46,9 @@ This skill adds writing guidance on top of those. When in doubt, the source file ## Documentation types -### Site documentation (Diataxis) +### Site documentation (Diátaxis) -The site follows the [Diataxis](https://diataxis.fr/) framework: +The site follows the [Diátaxis](https://diataxis.fr/) framework: | Mode | Directory | Purpose | |------|-----------|---------| @@ -58,14 +58,7 @@ The site follows the [Diataxis](https://diataxis.fr/) framework: **When in doubt, write a concept page.** Most new documentation should be concept pages. -| Concept page | How-to guide | -|---|---| -| **Preferred** — default choice | Use sparingly | -| Reference while working | Learning from scratch | -| One concept per page | Multi-step narrative | -| Scannable, minimal prose | Explains "why" at each step | -| No prerequisites | Has prerequisites | -| Jump in anywhere | Sequential | +The canonical guidance — full mode definitions and the concept vs how-to decision table — lives in `site/src/content/docs/how-to/write-guides.mdx`. Read it before choosing a mode. ### Package documentation diff --git a/site/src/content/docs/how-to/write-guides.mdx b/site/src/content/docs/how-to/write-guides.mdx index 5343beca6..c5247848e 100644 --- a/site/src/content/docs/how-to/write-guides.mdx +++ b/site/src/content/docs/how-to/write-guides.mdx @@ -10,11 +10,19 @@ import ServerCode from '@/components/Code/ServerCode.astro'; import { TabsRoot, TabsList, TabsPanel, Tab } from '@/components/Tabs.tsx'; import DocsLink from '@/components/docs/DocsLink.astro'; import Aside from '@/components/Aside.astro'; +import Demo from '@/components/docs/demos/Demo.astro'; +import BasicUsageDemoReact from '@/components/docs/demos/play-button/react/css/BasicUsage'; +import basicUsageReactTsx from '@/components/docs/demos/play-button/react/css/BasicUsage.tsx?raw'; +import basicUsageReactCss from '@/components/docs/demos/play-button/react/css/BasicUsage.css?raw'; +import BasicUsageDemoHtml from '@/components/docs/demos/play-button/html/css/BasicUsage.astro'; +import basicUsageHtml from '@/components/docs/demos/play-button/html/css/BasicUsage.html?raw'; +import basicUsageHtmlCss from '@/components/docs/demos/play-button/html/css/BasicUsage.css?raw'; +import basicUsageHtmlTs from '@/components/docs/demos/play-button/html/css/BasicUsage.ts?raw'; What is a guide? In this context, it's a document in the docs that's not an API reference. For API references, see Write reference pages. ## 1. Understand our documentation structure @@ -25,7 +33,16 @@ First, read and understand [Diátaxis](https://diataxis.fr/). We organize docume 2. **How-to guides** (`src/content/docs/how-to/`): Spans multiple concepts in order to achieve a specific outcome with step-by-step instructions. 3. **Reference pages** (`src/content/docs/reference/`): Component API documentation. These are scaffolded using the `api-reference` skill and the api-docs-builder. Again, see Write reference pages for details. -When in doubt, you probably want a concept page. +**When in doubt, write a concept page.** Most new documentation should be concept pages. Use this table to decide between the two: + +| Concept page | How-to guide | +|---|---| +| **Preferred** — default choice | Use sparingly | +| Reference while working | Learning from scratch | +| One concept per page | Multi-step narrative | +| Scannable, minimal prose | Explains "why" at each step | +| No prerequisites | Has prerequisites | +| Jump in anywhere | Sequential | ## 2. Create a guide in the correct content folder @@ -54,22 +71,24 @@ Next, open `src/docs.config.ts` and add your guide to the appropriate section of ```ts { - slug: 'how-to/write-guides', - title: 'Writing guides' + slug: 'how-to/write-guides' } ``` -If you want the guide to only apply to specific frameworks or styles, you can specify those as well: +The sidebar label defaults to the guide's `title` frontmatter; override it with `sidebarLabel`. If you want the guide to only apply to specific frameworks, you can specify that as well: ```ts { slug: 'how-to/write-guides', - title: 'Writing guides', - frameworks: ['react'], // Only for React - styles: ['css'] // Only for CSS + sidebarLabel: 'Writing guides', + frameworks: ['react'] // Only for React } ``` + + ## 4. Follow our writing style Keep documentation clear, human, and useful. Here are the key rules: @@ -87,7 +106,7 @@ Keep documentation clear, human, and useful. Here are the key rules: ## 5. Understand MDX and our components ### `` and `` -First, understand that the guide you write will be rendered for every framework / style combination (e.g., HTML + CSS, React + CSS) unless you restrict it in the sidebar config as shown above. +First, understand that the guide you write will be rendered for every framework / style combination (e.g., HTML + CSS, React + CSS) unless you restrict it to specific frameworks in the sidebar config as shown above. Use the `` and `` components to conditionally show content to just one framework or style: @@ -230,6 +249,24 @@ we can use 3 backticks ``` in new line and write snippet and close with 3 backti ``` +#### Code frames and titles + +Every standalone code block is automatically wrapped in a `` — the tabbed header and copy button you see on the examples above. You don't write it yourself; the `satteriCodeFrame` MDX plugin injects it. Code blocks inside an authored `` are left alone, since the tab group is already their frame. + +The frame's tab shows the language by default. To show a filename instead, add `title="..."` to the fence meta: + +````markdown +```ts title="App.ts" +console.log('Hello, Video.js!'); +``` +```` + +Which renders as: + +```ts title="App.ts" +console.log('Hello, Video.js!'); +``` + ### Code annotations You can annotate code blocks with special comments to highlight, diff, focus, or word-highlight specific lines. The annotation comments are stripped from the rendered output (and from copy/paste). @@ -443,7 +480,7 @@ You would just get To work around this, use `` instead of triple backticks. ```mdx @@ -476,6 +513,59 @@ function Component() { +### ``, for a live preview with tabbed source code + +Use `` to show a live, interactive example alongside the code that produces it. This is the standard pattern on reference pages (e.g., PlayButton). + +Pass the source files via the `files` prop — each entry has a `title`, `code` (a `?raw` import), and `lang` — and place the rendered demo in the default slot. Any `css` file in `files` is automatically scoped to the demo, so the demo's styles won't leak into the page. + +Demos are framework-specific, so wrap each variant in `` (and ``, if applicable): + +```mdx +import Demo from '@/components/docs/demos/Demo.astro'; +import BasicUsageDemoReact from '@/components/docs/demos/play-button/react/css/BasicUsage'; +import basicUsageReactTsx from '@/components/docs/demos/play-button/react/css/BasicUsage.tsx?raw'; +import basicUsageReactCss from '@/components/docs/demos/play-button/react/css/BasicUsage.css?raw'; + + + + + + + + +``` + +Which renders as: + + + + + + + + + + + + + + + + + +See the "Interactive Demos" section of `site/CLAUDE.md` for how to author the demo files themselves (directory structure, CSS class naming, and the HTML `.astro` wrapper). + ## Literally any other component This is just MDX, so you can import any old component and use it. To make that imported component look pretty, you might consider wrapping it in `` or placing it inside of a `` alongside code, as shown below. From 90aa3a861fd635ceadd5879064df698f1c78084c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 19:05:26 +0000 Subject: [PATCH 2/3] =?UTF-8?q?docs(site):=20encode=20Di=C3=A1taxis=20comp?= =?UTF-8?q?ass=20and=20mode-separation=20rule=20in=20write-guides?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the two-question compass with our three-mode mapping, note the deliberately absent tutorials mode, fold mode-quality hints into the mode list, and state the don't-mix-modes rule after the decision table. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Jk33yY4w5PkThQjkysDWgc --- site/src/content/docs/how-to/write-guides.mdx | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/site/src/content/docs/how-to/write-guides.mdx b/site/src/content/docs/how-to/write-guides.mdx index c5247848e..bbd85542e 100644 --- a/site/src/content/docs/how-to/write-guides.mdx +++ b/site/src/content/docs/how-to/write-guides.mdx @@ -29,10 +29,21 @@ Oh hey by the way. A lot of this knowledge is encoded in the `docs` Claude skill First, read and understand [Diátaxis](https://diataxis.fr/). We organize documentation into three modes: -1. **Concept pages** (`src/content/docs/concepts/`): Explain how and why things work. General understanding, spanning multiple APIs, can be applied to multiple outcomes. As we write guides, what are things we need people to understand in multiple places and don’t want to duplicate the content? -2. **How-to guides** (`src/content/docs/how-to/`): Spans multiple concepts in order to achieve a specific outcome with step-by-step instructions. +1. **Concept pages** (`src/content/docs/concepts/`): Explain how and why things work — design decisions, trade-offs, and context. General understanding, spanning multiple APIs, can be applied to multiple outcomes. As we write guides, what are things we need people to understand in multiple places and don’t want to duplicate the content? Diátaxis calls this mode "explanation." +2. **How-to guides** (`src/content/docs/how-to/`): Spans multiple concepts in order to achieve a specific outcome with step-by-step instructions. Address a real user goal, assume competence, and link to concept pages instead of explaining inline. 3. **Reference pages** (`src/content/docs/reference/`): Component API documentation. These are scaffolded using the `api-reference` skill and the api-docs-builder. Again, see Write reference pages for details. + + +To pick a mode, use the Diátaxis [compass](https://diataxis.fr/compass/). Ask two questions: does the content inform **action** (practical steps) or **cognition** (understanding)? And does it serve the reader's **study** (acquiring skills) or their **work** (applying them)? + +| | Informs action | Informs cognition | +|---|---|---| +| **Serves work** | How-to guide | Reference page | +| **Serves study** | How-to guide (Getting started) | Concept page | + **When in doubt, write a concept page.** Most new documentation should be concept pages. Use this table to decide between the two: | Concept page | How-to guide | @@ -44,6 +55,8 @@ First, read and understand [Diátaxis](https://diataxis.fr/). We organize docume | No prerequisites | Has prerequisites | | Jump in anywhere | Sequential | +Whichever mode you choose, **don't mix modes on one page**. Step-by-step instructions creeping into a concept page belong in a how-to guide; background explanation swelling a how-to step belongs in a concept page — link to it instead. Each mode serves a different reader need, and blending them dilutes both. + ## 2. Create a guide in the correct content folder Our guides are [MDX](https://mdxjs.com) files placed in the matching directory: From e163bf0af363be4bb83ff20f223445e5dbaab0e9 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 19:30:47 +0000 Subject: [PATCH 3/3] docs(site): clarify tutorials mode is omitted for now, not permanently Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Jk33yY4w5PkThQjkysDWgc --- site/src/content/docs/how-to/write-guides.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/content/docs/how-to/write-guides.mdx b/site/src/content/docs/how-to/write-guides.mdx index bbd85542e..e4148f4e4 100644 --- a/site/src/content/docs/how-to/write-guides.mdx +++ b/site/src/content/docs/how-to/write-guides.mdx @@ -34,7 +34,7 @@ First, read and understand [Diátaxis](https://diataxis.fr/). We organize docume 3. **Reference pages** (`src/content/docs/reference/`): Component API documentation. These are scaffolded using the `api-reference` skill and the api-docs-builder. Again, see Write reference pages for details. To pick a mode, use the Diátaxis [compass](https://diataxis.fr/compass/). Ask two questions: does the content inform **action** (practical steps) or **cognition** (understanding)? And does it serve the reader's **study** (acquiring skills) or their **work** (applying them)?