@brett_lamy/docstream 1.2.1 → 1.2.3

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.
@@ -37,20 +39,31 @@ function splitTableRow(row: string): string[] {
   const trimmed = row.trim().replace(/^\|/, "").replace(/\|$/, "")
   const cells: string[] = []
   let cur = ""
-  let inCode = false
   for (let k = 0; k < trimmed.length; k++) {
     const ch = trimmed[k]
-    if (ch === "\\" && trimmed[k + 1] === "|") {
-      cur += "|"
+    if (ch === "\\") {
+      // `\|` is a literal pipe (in code spans too); any other escape passes through for the inline parser.
+      cur += trimmed[k + 1] === "|" ? "|" : trimmed.slice(k, k + 2)
       k++
       continue
     }
     if (ch === "`") {
-      inCode = !inCode
-      cur += ch
+      // A code span (a backtick run closed by one of the same length) keeps its pipes; a lone run is literal.
+      let n = 1
+      while (trimmed[k + n] === "`") n++
+      const fence = "`".repeat(n)
+      let end = trimmed.indexOf(fence, k + n)
+      while (end !== -1 && (trimmed[end + n] === "`" || trimmed[end - 1] === "`")) {
+        let e = end
+        while (trimmed[e] === "`") e++
+        end = trimmed.indexOf(fence, e)
+      }
+      const stop = end === -1 ? k + n : end + n
+      cur += trimmed.slice(k, stop).replace(/\\\|/g, "|")
+      k = stop - 1
       continue
     }
-    if (ch === "|" && !inCode) {
+    if (ch === "|") {
       cells.push(cur)
       cur = ""
       continue
@@ -61,22 +74,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 +238,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 +340,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 +454,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 +674,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 +686,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 +712,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)}`
     }
@@ -158,7 +166,8 @@ function serializeBlock(b: Block): string {
       }
       // Escape pipes inside cell text so they don't break the GFM row.
       const cell = (c: Inline[]) => serializeInline(c).replace(/\|/g, "\\|")
-      const row = (cells: Inline[][]) => `| ${cells.map(cell).join(" | ")} |`
+      // An empty cell is written `| |`, as authors do.
+      const row = (cells: Inline[][]) => `|${cells.map((c) => ` ${cell(c)} `.replace(/^  $/, " ")).join("|")}|`
       const sep = `| ${b.header.map(() => "---").join(" | ")} |`
       return [row(b.header), sep, ...b.rows.map(row)].join("\n")
     }
@@ -167,18 +176,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 +234,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/index.ts

@@ -99,7 +99,9 @@ export type {
 export { parseDemoVariants, parseMarkdown, parseBlocks, trimPartialInlineToken } from "./gitbook/parse"
 export { fenceFor, serializeBlocks, serializeDemoFile, serializeMarkdown } from "./gitbook/serialize"
 export {
+  defaultInlineDelims,
   footnoteDefinitions,
+  inlineDelims,
   parseInline,
   plainText,
   refDefinitions,

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));
 }