@brett_lamy/docstream 1.2.1 → 1.2.2

package/README.md

@@ -107,6 +107,18 @@ Helpful context for the reader.
 
 Supported styles are `info`, `success`, `warning`, and `danger`.
 
+### Code fences
+
+````md
+```ts title="client.ts"
+const client = createClient()
+```
+````
+
+Titled (file) fences show line numbers; untitled fences don't. `lineNumbers="true"`
+or `lineNumbers="false"` overrides either way, and an explicit attribute is kept on
+serialize even when it matches the default.
+
 ### Tabs
 
 ````md
@@ -289,11 +301,30 @@ examples/button/sizes/
 ```
 
 `meta.height` is a minimum for single-file previews (in-page components may grow
-past it) and the stage height for the multi-file viewer. `className` / `surface`
-(a style object, CSS custom properties welcome) style the preview canvas,
-`status` shows a small label in the header ("Live", "Needs network"), and
-`variantsWidth` sizes the variant switch. Block-level demo roots fill the canvas
-width; intrinsically sized ones (a button, an image) are centred.
+past it; without a height they size to their content — hosts can set a floor with
+`--docs-demo-preview-min-height`) and the stage height for the multi-file viewer.
+`className` / `surface` (a style object, CSS custom properties welcome) style the
+preview canvas, `bleed` drops its padding, `status` shows a small label in the
+header ("Live", "Needs network"), and `variantsWidth` sizes the variant switch.
+The canvas is block flow: block-level demo roots fill its width and lay out as on a
+page (`max-width: 480px; margin: 0 auto` centres at 480px); intrinsically sized
+(inline-level) ones — a button, a badge, an image — are centred.
+
+Every `meta.json` field has a tag attribute of the same name:
+
+```md
+{% demo src="button/sizes" title="Sizes \"S\" to \"L\"" status="Live" bleed="true" className="brand"
+  surface="background: var(--brand-50); --demo-gap: 12px" variantsWidth="220" %}
+```
+
+(one line in practice). `surface` is written as CSS declarations; `bleed="false"`
+switches off a `meta.json` `bleed: true`. **Precedence:** a tag attribute wins,
+then `meta.json`, then the built-in default — field by field. Copy page folds
+`meta.json` into the tag, so the copied page renders the same without the resolver.
+
+Attribute values are double-quoted; inside them a double quote is written `\"`, a
+backslash `\\`, and `%}` as `%\}`. The serializer escapes, the parser unescapes
+(other backslashes are kept as written).
 
 #### Demos that carry their files (block form)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "publishConfig": {
     "access": "public"

package/src/demo/DemoViewer.tsx

@@ -38,6 +38,7 @@ import { PillTabs, Segmented, rovingKeyDown } from "../docs/controls"
 import { useDemoResolver, useDemoRuntime } from "./context"
 import { languageForPath } from "./glob"
 import { inlineDemoMarkdown } from "./markdown"
+import { cssToSurface, surfaceStyle, surfaceToCss } from "./surface"
 import type { DemoComponent, DemoFile, DemoMeta, DemoResolver, DemoVariant, InlineDemoRuntime } from "./types"
 
 export interface DemoViewerProps {
@@ -66,7 +67,23 @@ export interface DemoViewerProps {
   runtime?: InlineDemoRuntime
   /** Extra npm dependencies for the runtime, merged over `demoDependencies` from context. */
   dependencies?: Record<string, string>
+  /** Class on the viewer's outer element. (The preview canvas's class is `canvasClassName`.) */
   className?: string
+  /*
+   * Look. Each falls back to the resolver's `meta.json` field of the same name when unset —
+   * props (a `{% demo %}` tag's attributes) win over `meta.json`, which wins over the
+   * defaults — so a copied page renders the same with or without the resolver.
+   */
+  /** Status shown in the header (`meta.status`). */
+  status?: string
+  /** Full-bleed canvas without the padded surface (`meta.bleed`). */
+  bleed?: boolean
+  /** Extra class on the preview canvas (`meta.className`). */
+  canvasClassName?: string
+  /** Canvas inline style: an object like `meta.surface`, or CSS declarations as in the tag's `surface`. */
+  surface?: Record<string, string | number> | string
+  /** Width of the variant switch (`meta.variantsWidth`). */
+  variantsWidth?: number | string
 }
 
 /* ---------- data ---------- */
@@ -249,7 +266,11 @@ function DemoCanvas({ src, preview, variant, bleed, look }: {
   }
   if (preview.kind === "runtime") {
     return (
-      <div className="docs-demo-canvas docs-demo-canvas-bleed docs-demo-canvas-runtime" data-variant={variant}>
+      <div
+        className={["docs-demo-canvas docs-demo-canvas-bleed docs-demo-canvas-runtime", look?.className ?? ""].filter(Boolean).join(" ")}
+        style={surfaceStyle(look?.surface)}
+        data-variant={variant}
+      >
         <DemoErrorBoundary src={src || "demo"}>{preview.render(variant)}</DemoErrorBoundary>
       </div>
     )
@@ -258,7 +279,7 @@ function DemoCanvas({ src, preview, variant, bleed, look }: {
   return (
     <div
       className={["docs-demo-canvas", bleed ? "docs-demo-canvas-bleed" : "", look?.className ?? ""].filter(Boolean).join(" ")}
-      style={look?.surface as CSSProperties | undefined}
+      style={surfaceStyle(look?.surface)}
       data-variant={variant}
     >
       {component.status === "ready" ? (
@@ -498,7 +519,7 @@ function VariantSwitch({ variants, value, onChange, title, width }: {
       onChange={onChange}
       label={`${title} variant`}
       className={width === undefined ? "docs-demo-variants" : "docs-demo-variants docs-demo-variants-sized"}
-      style={width === undefined ? undefined : { width: typeof width === "number" ? `${width}px` : width }}
+      style={width === undefined ? undefined : { width: cssLength(width, "auto") }}
     />
   )
 }
@@ -600,10 +621,15 @@ export function DemoViewer(props: DemoViewerProps) {
   const layout: "single" | "multi" | null =
     layoutPref !== "auto" ? layoutPref : fileList ? (fileList.length > 1 ? "multi" : "single") : null
   const heightValue = props.height ?? metaValue?.height
-  const bleed = metaValue?.bleed
-  const look: CanvasLook | undefined = metaValue
-  const variantsWidth = metaValue?.variantsWidth
-  const status = metaValue?.status
+  // Look: the tag's attributes (props) first, then `meta.json`.
+  const bleed = props.bleed ?? metaValue?.bleed
+  const propSurface = typeof props.surface === "string" ? cssToSurface(props.surface) : props.surface
+  const look: CanvasLook = {
+    className: props.canvasClassName ?? metaValue?.className,
+    surface: propSurface ?? metaValue?.surface,
+  }
+  const variantsWidth = props.variantsWidth ?? metaValue?.variantsWidth
+  const status = props.status ?? metaValue?.status
   const [fullscreen, setFullscreen] = useState(false)
   const href = mode === "resolver" ? resolver?.href?.(src, variant ? { variant } : undefined) : undefined
   const baseId = useId()
@@ -637,6 +663,11 @@ export function DemoViewer(props: DemoViewerProps) {
     ...(props.layout ? { layout: props.layout } : {}),
     ...(props.variants?.length ? { variants: props.variants } : {}),
     ...(props.viewport ? { viewport: props.viewport } : {}),
+    ...(props.status ? { status: props.status } : {}),
+    ...(props.bleed !== undefined ? { bleed: props.bleed } : {}),
+    ...(props.canvasClassName ? { className: props.canvasClassName } : {}),
+    ...(props.surface ? { surface: typeof props.surface === "string" ? props.surface : surfaceToCss(props.surface) } : {}),
+    ...(props.variantsWidth !== undefined && props.variantsWidth !== "" ? { variantsWidth: String(props.variantsWidth) } : {}),
   }
   const copyDemo = () => inlineDemoMarkdown(node, fileList ?? [], metaValue)
 
@@ -676,8 +707,15 @@ export function DemoViewer(props: DemoViewerProps) {
           {runnable ? (
             <div
               className="docs-react-demo-preview docs-demo-single-preview"
-              // A hint, not a cap: in-page components may grow past it. An iframe needs a real height.
-              style={preview.kind === "runtime" ? { height: cssLength(heightValue, "360px") } : { minHeight: cssLength(heightValue, "120px") }}
+              // A hint, not a cap: in-page components may grow past it (no height: size to content;
+              // hosts may set a floor with --docs-demo-preview-min-height). An iframe needs a real height.
+              style={
+                preview.kind === "runtime"
+                  ? { height: cssLength(heightValue, "360px") }
+                  : heightValue === undefined || heightValue === ""
+                    ? undefined
+                    : { minHeight: cssLength(heightValue, "0px") }
+              }
             >
               {near ? <DemoCanvas src={src} preview={preview} variant={variant} bleed={bleed} look={look} /> : <Spinner />}
             </div>
@@ -844,6 +882,11 @@ export function DemoBlock({ node }: { node: DemoNode }) {
       files={node.files}
       entry={node.entry}
       streaming={node.open}
+      status={node.status}
+      bleed={node.bleed}
+      canvasClassName={node.className}
+      surface={node.surface}
+      variantsWidth={node.variantsWidth}
     />
   )
 }

package/src/demo/index.ts

@@ -11,6 +11,7 @@ export {
 } from "./glob"
 export type { GlobDemoResolverOptions } from "./glob"
 export { defaultDemoMarkdown, inlineDemoMarkdown, inlineDemoNode, resolveDemosToMarkdown, toInlineFiles } from "./markdown"
+export { cssToSurface, surfaceToCss } from "./surface"
 export type { DemoMarkdownFormat, ResolveDemosOptions, ResolvedDemo } from "./markdown"
 export type {
   DemoComponent,

package/src/demo/markdown.ts

@@ -1,9 +1,11 @@
 import type { DemoInlineFile, DemoNode } from "../gitbook/ast"
+import { TAG_ATTRS } from "../gitbook/attrs"
 import { flattenForPlainMarkdown } from "../gitbook/flatten"
 import { demoBody, fenceTracker, parseBlocks, parseMarkdown } from "../gitbook/parse"
 import { fenceFor, serializeBlocks, serializeMarkdown } from "../gitbook/serialize"
 import type { DemoFile, DemoMeta, DemoResolver } from "./types"
 import { languageForPath } from "./glob"
+import { surfaceToCss } from "./surface"
 
 export { fenceFor }
 
@@ -39,7 +41,7 @@ export interface ResolvedDemo {
   title: string
 }
 
-const TAG_RE = /^(\s*)\{%\s*demo(\s[^%]*?)?\s*\/?%\}\s*$/
+const TAG_RE = new RegExp(String.raw`^(\s*)\{%\s*demo(\s${TAG_ATTRS})?\s*\/?%\}\s*$`)
 
 function titleFor(src: string, node: DemoNode, meta: DemoMeta | undefined) {
   return node.title ?? meta?.title ?? (src.split("/").pop() || src || "Demo")
@@ -77,7 +79,9 @@ export function toInlineFiles(files: DemoFile[]): DemoInlineFile[] {
 /**
  * A demo as a self-contained block-form `{% demo %}`: the node's attributes, with the
  * folder's `meta.json` defaults folded in (so the block renders the same without the
- * resolver), and `files` as inline fences.
+ * resolver) — title, description, height, layout, variants, entry and the look fields
+ * `status`, `bleed`, `className`, `surface` (as CSS declarations) and `variantsWidth` —
+ * and `files` as inline fences. Tag attributes win over `meta.json` where both exist.
  */
 export function inlineDemoNode(node: DemoNode, files: DemoFile[], meta?: DemoMeta): DemoNode {
   const inline = toInlineFiles(files)
@@ -87,6 +91,11 @@ export function inlineDemoNode(node: DemoNode, files: DemoFile[], meta?: DemoMet
   const layout = node.layout ?? meta?.layout
   const variants = node.variants?.length ? node.variants : meta?.variants?.length ? meta.variants : undefined
   const entry = node.entry ?? (meta?.entry && inline[0]?.path !== meta.entry ? meta.entry : undefined)
+  const status = node.status ?? meta?.status
+  const bleed = node.bleed ?? meta?.bleed
+  const className = node.className ?? meta?.className
+  const surface = node.surface ?? (meta?.surface ? surfaceToCss(meta.surface) : undefined)
+  const variantsWidth = node.variantsWidth ?? (meta?.variantsWidth === undefined || meta.variantsWidth === "" ? undefined : String(meta.variantsWidth))
   return {
     type: "demo",
     src: node.src,
@@ -97,6 +106,11 @@ export function inlineDemoNode(node: DemoNode, files: DemoFile[], meta?: DemoMet
     ...(variants ? { variants } : {}),
     ...(node.viewport ? { viewport: node.viewport } : {}),
     ...(entry ? { entry } : {}),
+    ...(status ? { status } : {}),
+    ...(bleed === undefined ? {} : { bleed }),
+    ...(className ? { className } : {}),
+    ...(surface ? { surface } : {}),
+    ...(variantsWidth ? { variantsWidth } : {}),
     ...(inline.length ? { files: inline } : {}),
   }
 }
@@ -123,7 +137,7 @@ export async function resolveDemosToMarkdown(
   options: ResolveDemosOptions = {},
 ): Promise<string> {
   // Plain output also flattens docstream-only presentation blocks (command boxes, titled tabs).
-  if (options.format === "plain" && /\{%\s*(?:command\b|tabs\s[^%]*\btitle=)/.test(markdown)) {
+  if (options.format === "plain" && /\{%\s*(?:command\b|tabs\s(?:[^%\n]|%(?!\}))*\btitle=)/.test(markdown)) {
     markdown = serializeMarkdown(flattenForPlainMarkdown(parseMarkdown(markdown)))
   }
   const lines = markdown.split("\n")

package/src/demo/surface.ts

@@ -0,0 +1,67 @@
+import type { CSSProperties } from "react"
+
+/*
+ * A demo canvas's `surface` (inline style) has two spellings:
+ * - `meta.json`: an object, `{ "background": "var(--brand-50)", "--demo-gap": "12px", "padding": 12 }`;
+ * - the `{% demo surface="…" %}` attribute: CSS declarations,
+ *   `background: var(--brand-50); --demo-gap: 12px; padding: 12`.
+ * Keys are kept as written (camelCase, kebab-case or custom properties).
+ */
+
+/** A `meta.json` surface object as the declaration string the demo tag carries. */
+export function surfaceToCss(surface: Record<string, string | number>): string {
+  return Object.entries(surface)
+    .filter(([key, value]) => key.trim() && value !== undefined && value !== null && String(value).trim() !== "")
+    .map(([key, value]) => `${key.trim()}: ${String(value).trim()}`)
+    .join("; ")
+}
+
+/** Split on `;` outside parentheses and quotes (`url("a;b")` stays whole). */
+function declarations(css: string): string[] {
+  const out: string[] = []
+  let depth = 0
+  let quote = ""
+  let current = ""
+  for (const ch of css) {
+    if (quote) {
+      if (ch === quote) quote = ""
+    } else if (ch === '"' || ch === "'") quote = ch
+    else if (ch === "(") depth++
+    else if (ch === ")") depth = Math.max(0, depth - 1)
+    else if (ch === ";" && depth === 0) {
+      out.push(current)
+      current = ""
+      continue
+    }
+    current += ch
+  }
+  out.push(current)
+  return out
+}
+
+/**
+ * The tag's declaration string as a React style object. Custom properties keep their
+ * name; `kebab-case` becomes camelCase; plain numbers on ordinary properties become
+ * numbers (so `padding: 12` means 12px, as it does in `meta.json`).
+ */
+export function cssToSurface(css: string): Record<string, string | number> {
+  const style: Record<string, string | number> = {}
+  for (const declaration of declarations(css)) {
+    const colon = declaration.indexOf(":")
+    if (colon < 0) continue
+    const key = declaration.slice(0, colon).trim()
+    const value = declaration.slice(colon + 1).trim()
+    if (!key || !value) continue
+    if (key.startsWith("--")) {
+      style[key] = value
+      continue
+    }
+    const name = key.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())
+    style[name] = /^-?\d+(?:\.\d+)?$/.test(value) ? Number(value) : value
+  }
+  return style
+}
+
+export function surfaceStyle(surface: Record<string, string | number> | undefined): CSSProperties | undefined {
+  return surface && Object.keys(surface).length ? (surface as CSSProperties) : undefined
+}

package/src/gitbook/ast.ts

@@ -67,7 +67,16 @@ export interface CodeBlockNode {
   type: "code"
   language: string | null
   title: string | null
+  /**
+   * Show line numbers. Defaults (when the fence doesn't say) to on for titled fences and
+   * off for untitled ones; `lineNumbers="true"` / `"false"` overrides.
+   */
   lineNumbers: boolean
+  /**
+   * The source wrote `lineNumbers` (or `showLineNumbers`) explicitly: the serializer keeps
+   * the attribute even when it matches the default, so pages round-trip byte-for-byte.
+   */
+  lineNumbersExplicit?: boolean
   code: string
   /** Run a React/JSX/TSX entry file in the optional almost-node preview. */
   live?: boolean
@@ -201,8 +210,11 @@ export interface DemoInlineFile {
  * A live demo: `{% demo src="<page>/<example>" %}`. With a host `DemoResolver`
  * that knows `src`, the example folder is the authority for the component, its
  * source files and its defaults; attributes here override the folder's
- * `meta.json`. The block form carries the files inline so the Markdown renders
- * anywhere, resolver or not:
+ * `meta.json` field by field (tag attribute first, then `meta.json`, then the built-in
+ * default) — including the look attributes `status`, `bleed`, `className`, `surface` and
+ * `variantsWidth`, which Copy page writes so the block renders the same without the resolver.
+ * The block form carries the files inline so the Markdown renders anywhere, resolver
+ * or not:
  *
  *     {% demo src="composer/scroll-fab" title="Scroll → FAB" %}
  *     ```tsx title="index.tsx"
@@ -225,6 +237,19 @@ export interface DemoNode {
   viewport?: DemoViewport
   /** Entry file among the inline files (`entry="App.tsx"`). Defaults to the first file. */
   entry?: string
+  /** Short status shown in the demo header (`status="Live"`). */
+  status?: string
+  /** Drop the padded preview surface (`bleed="true"`) for demos with their own full-bleed frame. */
+  bleed?: boolean
+  /** Extra class on the preview canvas (`className="brand-surface"`). */
+  className?: string
+  /**
+   * Inline style for the preview canvas as CSS declarations, kept verbatim:
+   * `surface="background: var(--brand-50); --demo-gap: 12px"`.
+   */
+  surface?: string
+  /** Width of the variant switch, kept verbatim (`"240"`, `"16rem"`). */
+  variantsWidth?: string
   /** Files carried inline by the block form, in document order. */
   files?: DemoInlineFile[]
   /**

package/src/gitbook/attrs.ts

@@ -0,0 +1,39 @@
+/*
+ * Tag and fence attribute values (`{% demo title="…" %}`, ```` ```ts title="…" ````).
+ *
+ * Values are double-quoted. On serialize a backslash becomes `\\`, a double quote `\"`,
+ * and the tag terminator `%}` becomes `%\}` — so a value can never end its tag early or
+ * truncate at a quote. On parse `\\`, `\"` and `\}` are unescaped; any other backslash is
+ * kept literally (so `C:\temp` written by hand still reads as written).
+ */
+
+/** Escape one attribute value for a double-quoted `name="…"` pair. */
+export function escapeAttr(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%\}/g, "%\\}")
+}
+
+/** Undo `escapeAttr`. */
+export function unescapeAttr(raw: string): string {
+  return raw.replace(/\\(["\\}])/g, "$1")
+}
+
+/** ` name="value"` with the value escaped (leading space included). */
+export function attr(name: string, value: string | number | boolean): string {
+  return ` ${name}="${escapeAttr(String(value))}"`
+}
+
+/** Every `name="value"` pair in `raw` (escapes honoured, values unescaped). */
+export function parseAttrs(raw: string | undefined): Record<string, string> {
+  const attrs: Record<string, string> = {}
+  if (!raw) return attrs
+  for (const m of raw.matchAll(/([\w-]+)="((?:[^"\\]|\\.)*)"/g)) {
+    attrs[m[1]] = unescapeAttr(m[2])
+  }
+  return attrs
+}
+
+/**
+ * The attribute part of a `{% name … %}` tag, as a regex source: anything up to the
+ * closing `%}` (a lone `%` is fine; `%}` inside a value is always escaped as `%\}`).
+ */
+export const TAG_ATTRS = String.raw`(?:[^%\n]|%(?!\}))*?`

package/src/gitbook/flatten.ts

@@ -19,7 +19,7 @@ export function flattenBlocks(blocks: Block[]): Block[] {
   return blocks.flatMap((b): Block[] => {
     switch (b.type) {
       case "command":
-        return [{ type: "code", language: "sh", title: null, lineNumbers: true, code: b.command }]
+        return [{ type: "code", language: "sh", title: null, lineNumbers: false, code: b.command }]
       case "tabs":
         if (b.title) {
           return [

package/src/gitbook/index.ts

@@ -1,6 +1,7 @@
 // Pure GitBook markdown engine (no React, no mermaid/streamdown). Safe to import
 // in non-DOM environments such as a server-side AI agent or a Cloudflare Worker.
 export type * from "./ast"
+export { escapeAttr, unescapeAttr } from "./attrs"
 export { closesFence, demoBody, fenceOpener, fenceTracker, parseDemoVariants, parseMarkdown, parseBlocks, trimPartialInlineToken } from "./parse"
 export { fenceFor, serializeBlocks, serializeDemoFile, serializeMarkdown } from "./serialize"
 export { footnoteDefinitions, parseInline, plainText, refDefinitions, serializeInline, serializeReference } from "./inline"

package/src/gitbook/parse.ts

@@ -1,5 +1,6 @@
 import type {
   Block,
+  CodeBlockNode,
   ColumnNode,
   CommandNode,
   DemoInlineFile,
@@ -15,6 +16,7 @@ import type {
   TabNode,
   UpdateNode,
 } from "./ast"
+import { TAG_ATTRS, parseAttrs } from "./attrs"
 import { footnoteDefinitions, parseInline, plainText, refDefinitions } from "./inline"
 
 // Minimal HTML-inline → markdown-inline bridge for HTML table cells.
@@ -61,22 +63,23 @@ function splitTableRow(row: string): string[] {
   return cells
 }
 
-const TEMPLATE_RE = /^\s*\{%\s*(\S+?)(\s+[^%]*?)?\s*%\}\s*$/
-
-function parseAttrs(raw: string | undefined): Record<string, string> {
-  const attrs: Record<string, string> = {}
-  if (!raw) return attrs
-  for (const m of raw.matchAll(/([\w-]+)="([^"]*)"/g)) {
-    attrs[m[1]] = m[2]
-  }
-  return attrs
-}
+const TEMPLATE_RE = new RegExp(String.raw`^\s*\{%\s*(\S+?)(\s+${TAG_ATTRS})?\s*%\}\s*$`)
 
 function booleanAttr(attrs: Record<string, string>, key: string): boolean | undefined {
   if (!(key in attrs)) return undefined
   return attrs[key] !== "false"
 }
 
+/**
+ * A fence's line numbers: `lineNumbers` / `showLineNumbers` when written (remembered as
+ * explicit so the attribute round-trips even when it equals the default), otherwise on for
+ * titled (file) fences and off for untitled ones.
+ */
+function lineNumbersFrom(attrs: Record<string, string>, titled: boolean): Pick<CodeBlockNode, "lineNumbers" | "lineNumbersExplicit"> {
+  const written = booleanAttr(attrs, "lineNumbers") ?? booleanAttr(attrs, "showLineNumbers")
+  return written === undefined ? { lineNumbers: titled } : { lineNumbers: written, lineNumbersExplicit: true }
+}
+
 function positiveNumberAttr(attrs: Record<string, string>, key: string): number | undefined {
   if (!(key in attrs)) return undefined
   const value = Number(attrs[key])
@@ -224,7 +227,7 @@ export function parseDemoVariants(raw: string): DemoVariantOption[] {
 }
 
 /** `{% command %}npm install x{% endcommand %}` on one line. */
-const COMMAND_ONE_LINE_RE = /^\s*\{%\s*command(\s[^%]*?)?\s*%\}(.*?)\{%\s*endcommand\s*%\}\s*$/
+const COMMAND_ONE_LINE_RE = new RegExp(String.raw`^\s*\{%\s*command(\s${TAG_ATTRS})?\s*%\}(.*?)\{%\s*endcommand\s*%\}\s*$`)
 
 function commandNode(attrs: Record<string, string>, raw: string): CommandNode {
   const overrides: NonNullable<CommandNode["overrides"]> = {}
@@ -326,6 +329,11 @@ function parseDemoTag(attrs: Record<string, string>): DemoNode {
     ...(variants.length ? { variants } : {}),
     ...((DEMO_VIEWPORTS as string[]).includes(attrs.viewport) ? { viewport: attrs.viewport as DemoViewport } : {}),
     ...(attrs.entry ? { entry: attrs.entry } : {}),
+    ...(attrs.status ? { status: attrs.status } : {}),
+    ...(booleanAttr(attrs, "bleed") === undefined ? {} : { bleed: booleanAttr(attrs, "bleed") }),
+    ...(attrs.className ? { className: attrs.className } : {}),
+    ...(attrs.surface?.trim() ? { surface: attrs.surface } : {}),
+    ...(attrs.variantsWidth ? { variantsWidth: attrs.variantsWidth } : {}),
   }
 }
 
@@ -435,7 +443,7 @@ export function parseBlocks(lines: string[]): Block[] {
         const code = inner.find((b) => b.type === "code")
         if (code && code.type === "code") {
           code.title = tag.attrs.title ?? null
-          code.lineNumbers = booleanAttr(tag.attrs, "lineNumbers") ?? booleanAttr(tag.attrs, "showLineNumbers") ?? true
+          Object.assign(code, lineNumbersFrom(tag.attrs, code.title !== null))
           code.live = tag.attrs.live === "true"
           code.entry = tag.attrs.entry ?? null
           blocks.push(code)
@@ -655,7 +663,9 @@ export function parseBlocks(lines: string[]): Block[] {
     const fence = trimmed.match(/^(`{3,}|~{3,})([^\s`]*)?(?:\s+(.*?))?\s*$/)
     if (fence) {
       flushParagraph()
-      const attrs = parseAttrs(fence[3])
+      // ```` ```title="x" ```` (attributes, no language): the first word is not a language.
+      const bareAttrs = !!fence[2]?.includes("=")
+      const attrs = parseAttrs(bareAttrs ? [fence[2], fence[3]].filter(Boolean).join(" ") : fence[3])
       const code: string[] = []
       i++
       while (i < lines.length && !lines[i].trim().startsWith(fence[1])) {
@@ -665,9 +675,9 @@ export function parseBlocks(lines: string[]): Block[] {
       i++
       blocks.push({
         type: "code",
-        language: fence[2] || null,
+        language: (!bareAttrs && fence[2]) || null,
         title: attrs.title ?? null,
-        lineNumbers: booleanAttr(attrs, "lineNumbers") ?? booleanAttr(attrs, "showLineNumbers") ?? true,
+        ...lineNumbersFrom(attrs, attrs.title !== undefined),
         code: code.join("\n"),
         ...(booleanAttr(attrs, "live") === undefined ? {} : { live: booleanAttr(attrs, "live") }),
         ...(attrs.entry ? { entry: attrs.entry } : {}),
@@ -691,7 +701,7 @@ export function parseBlocks(lines: string[]): Block[] {
         code.push(lines[i].slice(4))
         i++
       }
-      blocks.push({ type: "code", language: null, title: null, lineNumbers: true, code: code.join("\n") })
+      blocks.push({ type: "code", language: null, title: null, lineNumbers: false, code: code.join("\n") })
       continue
     }
 

package/src/gitbook/serialize.ts

@@ -1,4 +1,5 @@
 import type { Block, DemoInlineFile, DemoNode, DocumentNode, Inline, ListItemNode } from "./ast"
+import { attr } from "./attrs"
 import { serializeInline, serializeReference } from "./inline"
 
 export function serializeMarkdown(doc: DocumentNode): string {
@@ -34,36 +35,38 @@ function serializeBlock(b: Block): string {
     }
 
     case "code": {
+      // Line numbers default to on for titled fences, off for untitled ones.
+      const numbersByDefault = b.title !== null && b.title !== undefined && b.title !== ""
       const attrs = [
-        b.title ? `title="${b.title}"` : "",
-        !b.lineNumbers ? `lineNumbers="false"` : "",
-        b.live ? `live="true"` : "",
-        b.entry ? `entry="${b.entry}"` : "",
-        b.collapsedCodeLines ? `collapsedCodeLines="${b.collapsedCodeLines}"` : "",
-        b.expandedCodeLines ? `expandedCodeLines="${b.expandedCodeLines}"` : "",
-      ].filter(Boolean)
-      const info = [b.language ?? "", ...attrs].filter(Boolean).join(" ")
+        b.title ? attr("title", b.title) : "",
+        b.lineNumbers !== numbersByDefault || b.lineNumbersExplicit ? attr("lineNumbers", b.lineNumbers) : "",
+        b.live ? attr("live", true) : "",
+        b.entry ? attr("entry", b.entry) : "",
+        b.collapsedCodeLines ? attr("collapsedCodeLines", b.collapsedCodeLines) : "",
+        b.expandedCodeLines ? attr("expandedCodeLines", b.expandedCodeLines) : "",
+      ].join("")
+      const info = `${b.language ?? ""}${b.language ? attrs : attrs.trimStart()}`
       return `\`\`\`${info}\n${b.code}\n\`\`\``
     }
 
     case "hint":
-      return `{% hint style="${b.style}" %}\n${serializeBlocks(b.children)}\n{% endhint %}`
+      return `{% hint${attr("style", b.style)} %}\n${serializeBlocks(b.children)}\n{% endhint %}`
 
     case "tabs": {
       const attrs = [
-        b.title ? ` title="${b.title}"` : "",
-        b.title && b.level && b.level !== 2 ? ` level="${b.level}"` : "",
-        b.sync ? ` sync="${b.sync}"` : "",
+        b.title ? attr("title", b.title) : "",
+        b.title && b.level && b.level !== 2 ? attr("level", b.level) : "",
+        b.sync ? attr("sync", b.sync) : "",
       ].join("")
       return `{% tabs${attrs} %}\n${b.tabs
-        .map((t) => `{% tab title="${t.title}" %}\n${serializeBlocks(t.children)}\n{% endtab %}`)
+        .map((t) => `{% tab${attr("title", t.title)} %}\n${serializeBlocks(t.children)}\n{% endtab %}`)
         .join("\n\n")}\n{% endtabs %}`
     }
 
     case "command": {
       const attrs = [
-        ...(["pnpm", "yarn", "bun"] as const).map((pm) => (b.overrides?.[pm] ? ` ${pm}="${b.overrides[pm]}"` : "")),
-        b.sync && b.sync !== "pm" ? ` sync="${b.sync}"` : "",
+        ...(["pnpm", "yarn", "bun"] as const).map((pm) => (b.overrides?.[pm] ? attr(pm, b.overrides[pm]) : "")),
+        b.sync && b.sync !== "pm" ? attr("sync", b.sync) : "",
       ].join("")
       return b.command.includes("\n")
         ? `{% command${attrs} %}\n${b.command}\n{% endcommand %}`
@@ -83,43 +86,48 @@ function serializeBlock(b: Block): string {
 
     case "embed": {
       const attrs = [
-        ` url="${b.url}"`,
-        b.title ? ` title="${b.title}"` : "",
-        b.poster ? ` poster="${b.poster}"` : "",
-        b.autoplay === undefined ? "" : ` autoplay="${b.autoplay}"`,
-        b.loop === undefined ? "" : ` loop="${b.loop}"`,
-        b.muted === undefined ? "" : ` muted="${b.muted}"`,
-        b.controls === undefined ? "" : ` controls="${b.controls}"`,
+        attr("url", b.url),
+        b.title ? attr("title", b.title) : "",
+        b.poster ? attr("poster", b.poster) : "",
+        b.autoplay === undefined ? "" : attr("autoplay", b.autoplay),
+        b.loop === undefined ? "" : attr("loop", b.loop),
+        b.muted === undefined ? "" : attr("muted", b.muted),
+        b.controls === undefined ? "" : attr("controls", b.controls),
       ].join("")
       return `{% embed${attrs} %}`
     }
 
     case "content-ref":
-      return `{% content-ref url="${b.url}" %}\n${serializeInline(b.children)}\n{% endcontent-ref %}`
+      return `{% content-ref${attr("url", b.url)} %}\n${serializeInline(b.children)}\n{% endcontent-ref %}`
 
     case "source-ref": {
       const attrs = [
-        ` mount="${b.mount}"`,
-        ` path="${b.path}"`,
-        ` export="${b.exportName}"`,
-        ` kind="${b.kind}"`,
-        b.title ? ` title="${b.title}"` : "",
+        attr("mount", b.mount),
+        attr("path", b.path),
+        attr("export", b.exportName),
+        attr("kind", b.kind),
+        b.title ? attr("title", b.title) : "",
       ].join("")
       return `{% source-ref${attrs} %}`
     }
 
     case "demo": {
       const attrs = [
-        ` src="${b.src}"`,
-        b.title ? ` title="${b.title}"` : "",
-        b.description ? ` description="${b.description}"` : "",
-        b.height ? ` height="${b.height}"` : "",
-        b.layout ? ` layout="${b.layout}"` : "",
+        attr("src", b.src),
+        b.title ? attr("title", b.title) : "",
+        b.description ? attr("description", b.description) : "",
+        b.height ? attr("height", b.height) : "",
+        b.layout ? attr("layout", b.layout) : "",
         b.variants?.length
-          ? ` variants="${b.variants.map((v) => (v.label === v.id ? v.id : `${v.id}:${v.label}`)).join(",")}"`
+          ? attr("variants", b.variants.map((v) => (v.label === v.id ? v.id : `${v.id}:${v.label}`)).join(","))
           : "",
-        b.viewport ? ` viewport="${b.viewport}"` : "",
-        b.entry ? ` entry="${b.entry}"` : "",
+        b.viewport ? attr("viewport", b.viewport) : "",
+        b.entry ? attr("entry", b.entry) : "",
+        b.status ? attr("status", b.status) : "",
+        b.bleed === undefined ? "" : attr("bleed", b.bleed),
+        b.className ? attr("className", b.className) : "",
+        b.surface ? attr("surface", b.surface) : "",
+        b.variantsWidth ? attr("variantsWidth", b.variantsWidth) : "",
       ].join("")
       return `{% demo${attrs} %}${serializeDemoFiles(b)}`
     }
@@ -167,18 +175,18 @@ function serializeBlock(b: Block): string {
       return `$$\n${b.formula}\n$$`
 
     case "updates":
-      return `{% updates${b.format ? ` format="${b.format}"` : ""} %}\n${b.updates
+      return `{% updates${b.format ? attr("format", b.format) : ""} %}\n${b.updates
         .map(
           (u) =>
-            `{% update date="${u.date}" %}\n${serializeBlocks(u.children)}\n{% endupdate %}`
+            `{% update${attr("date", u.date)} %}\n${serializeBlocks(u.children)}\n{% endupdate %}`
         )
         .join("\n\n")}\n{% endupdates %}`
 
     case "openapi-operation": {
       const attrs = [
-        b.spec ? ` spec="${b.spec}"` : "",
-        b.path ? ` path="${b.path}"` : "",
-        b.method ? ` method="${b.method}"` : "",
+        b.spec ? attr("spec", b.spec) : "",
+        b.path ? attr("path", b.path) : "",
+        b.method ? attr("method", b.method) : "",
       ].join("")
       const inner = b.specUrl ? `\n[${b.label || b.spec || "OpenAPI"}](${b.specUrl})` : ""
       return `{% openapi-operation${attrs} %}${inner}\n{% endopenapi-operation %}`
@@ -225,7 +233,7 @@ export function fenceFor(content: string): string {
 /** One inline demo file as a titled fence. */
 export function serializeDemoFile(file: DemoInlineFile): string {
   const fence = fenceFor(file.content)
-  return `${fence}${file.language ?? ""} title="${file.path}"\n${file.content}\n${fence}`
+  return `${fence}${file.language ?? ""}${attr("title", file.path)}\n${file.content}\n${fence}`
 }
 
 /** The body of a block-form `{% demo %}`: files as titled fences, then `{% enddemo %}`. Empty without files. */

package/src/styles.css

@@ -1530,9 +1530,13 @@
   margin-bottom: 12px;
 }
 
-:is([data-docstream], .docs-article) .docs-tabs-section-head .docs-tabs-section-title {
+/* The heading sits centred on the switch's row: no block margin, padding or rule of its own
+   (page heading rules — docstream's and a host's `h2 { padding-top }` — would push it off
+   centre; 0,4,0 outranks them). */
+:is([data-docstream], .docs-article) .docs-tabs-section > .docs-tabs-section-head > .docs-tabs-section-title {
+  align-self: center;
   margin: 0;
-  padding-bottom: 0;
+  padding-block: 0;
   border-bottom: 0;
   scroll-margin-top: 80px;
 }
@@ -1543,15 +1547,18 @@
   gap: 10px;
 }
 
-.docs-tabs-section-body > [data-docstream-blocks] > * {
+/* One 10px rhythm inside a section. These must outrank the generic block spacing
+   (`:is([data-docstream], .docs-article) [data-docstream-blocks] > :is(.docs-code, …)`,
+   headings and demos, specificity 0,3,0), hence the extra `.docs-tabs-section >` (0,4,0). */
+:is([data-docstream], .docs-article) .docs-tabs-section > .docs-tabs-section-body > [data-docstream-blocks] > * {
   margin-block: 0 10px;
 }
 
-.docs-tabs-section-body > [data-docstream-blocks] > :last-child {
+:is([data-docstream], .docs-article) .docs-tabs-section > .docs-tabs-section-body > [data-docstream-blocks] > :last-child {
   margin-bottom: 0;
 }
 
-.docs-tabs-section-body > [data-docstream-blocks] > p {
+:is([data-docstream], .docs-article) .docs-tabs-section > .docs-tabs-section-body > [data-docstream-blocks] > p {
   color: var(--gb-muted-foreground);
   font-size: 0.93em;
 }
@@ -1945,35 +1952,36 @@
   opacity: 1;
 }
 
-/* Block-level demo roots fill the width (place-items: center would shrink them to their
-   content); content is centred vertically, and intrinsically sized roots horizontally. */
+/* The canvas is block flow, so a block-level demo root lays out exactly as it would on a
+   page: it fills the width, and `max-width: 480px; margin: 0 auto` centres it at 480px (a
+   grid or flex canvas would shrink it to its content). Intrinsically sized roots — inline /
+   inline-block / inline-flex elements such as a lone button, badge or image — sit on the
+   canvas's centred line box. Content is centred vertically (`align-content` on a block
+   container). The canvas's `text-align: center` stops at its children: the reset below has
+   zero specificity, so any rule of the demo's own wins. */
 .docs-demo-canvas {
-  display: grid;
+  display: block;
   align-content: center;
-  justify-items: stretch;
   box-sizing: border-box;
   min-height: 100%;
   padding: 28px 24px;
   color: var(--foreground, var(--gb-panel-foreground));
+  text-align: center;
 }
 
-.docs-demo-canvas > * {
-  min-width: 0;
+:where(.docs-demo-canvas) > * {
   max-width: 100%;
-}
-
-.docs-demo-canvas > :where(button, a, img, svg, video, canvas, input, select, textarea, label, span, code) {
-  justify-self: center;
+  text-align: start;
 }
 
 .docs-demo-canvas-bleed {
-  display: block;
-  place-items: normal;
+  align-content: normal;
   height: 100%;
   padding: 0;
+  text-align: start;
 }
 
-.docs-demo-canvas-bleed > * {
+:where(.docs-demo-canvas-bleed) > * {
   max-width: none;
 }
 
@@ -2241,9 +2249,11 @@
   background: var(--gb-hover);
 }
 
+/* Sizes to its content; a `height` in meta or on the tag sets a minimum (inline style), and
+   hosts may set a floor for every single-file preview with --docs-demo-preview-min-height. */
 .docs-demo-single-preview {
   display: grid;
-  min-height: 120px;
+  min-height: var(--docs-demo-preview-min-height, 0px);
   background: var(--background, var(--gb-panel));
 }