@brett_lamy/docstream 1.0.0 → 1.1.0

package/src/docs/PageActions.tsx

@@ -0,0 +1,219 @@
+/* "Copy page ▾": copy the page as Markdown (with {% demo %} blocks resolved into their real files),
+   view it as Markdown, or open it in ChatGPT / Claude. */
+import { useEffect, useId, useRef, useState, type KeyboardEvent, type ReactNode } from "react"
+import { AnimatePresence, motion, useReducedMotion } from "framer-motion"
+import { ArrowUpRight, ChevronDown, FileText } from "lucide-react"
+
+import { useDemoResolver } from "../demo/context"
+import { resolveDemosToMarkdown, type ResolveDemosOptions } from "../demo/markdown"
+import type { DemoResolver } from "../demo/types"
+import { CopyIcon, useCopied } from "./copy"
+
+export type DocPageAction = "copy" | "view" | "chatgpt" | "claude"
+
+export interface DocPageActionsOptions {
+  /**
+   * Public URL of this page as Markdown (e.g. `/md/button.md`). "View as Markdown" opens it and the
+   * ChatGPT / Claude prompts reference it. Without it, "View" opens the resolved Markdown as a
+   * blob and the prompts reference `pageUrl` (default: the current location).
+   */
+  markdownUrl?: string
+  pageUrl?: string
+  /** The question handed to ChatGPT / Claude. */
+  prompt?: (url: string) => string
+  /** Which menu entries to show, in order. Defaults to all four. */
+  actions?: DocPageAction[]
+  /** Final touch on the copied Markdown (e.g. append a "Source:" footer). */
+  transform?: (markdown: string) => string
+  /** Options for resolving `{% demo %}` blocks. */
+  demoOptions?: ResolveDemosOptions
+  /** Overrides the resolver from context. */
+  resolver?: DemoResolver
+  className?: string
+}
+
+export interface DocPageActionsProps extends DocPageActionsOptions {
+  /** The page's Markdown source (or a function producing it on demand). */
+  markdown: string | (() => string | Promise<string>)
+}
+
+const OpenAIGlyph = () => (
+  <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.9" aria-hidden="true">
+    {[0, 60, 120].map((a) => (
+      <rect key={a} x="8.6" y="2.6" width="6.8" height="18.8" rx="3.4" transform={`rotate(${a} 12 12)`} />
+    ))}
+  </svg>
+)
+
+const AnthropicGlyph = () => (
+  <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+    <path d="M17.3 3.54h-3.67l6.7 16.92H24zM6.7 3.54 0 20.46h3.74l1.37-3.55h7.01l1.37 3.55h3.74L10.54 3.54zm-.37 10.22 2.29-5.94 2.29 5.94z" />
+  </svg>
+)
+
+const defaultPrompt = (url: string) => `Read ${url}, I want to ask questions about it.`
+
+interface MenuItem {
+  id: DocPageAction
+  icon: ReactNode
+  label: string
+  hint: string
+  href?: string
+  run?: () => void
+}
+
+/** Resolves the page Markdown (demos inlined) for copying or exporting. */
+async function pageMarkdown(props: DocPageActionsProps, resolver: DemoResolver | undefined) {
+  const source = typeof props.markdown === "function" ? await props.markdown() : props.markdown
+  const resolved = await resolveDemosToMarkdown(source, resolver, props.demoOptions)
+  return props.transform ? props.transform(resolved) : resolved
+}
+
+/** A shadcn-style split button: "Copy page" plus a menu of Markdown / AI actions. */
+export function DocPageActions(props: DocPageActionsProps) {
+  const resolver = useDemoResolver(props.resolver)
+  const { copied, copy } = useCopied()
+  const [open, setOpen] = useState(false)
+  const reduced = useReducedMotion()
+  const root = useRef<HTMLDivElement | null>(null)
+  const trigger = useRef<HTMLButtonElement | null>(null)
+  const menuId = useId()
+
+  useEffect(() => {
+    if (!open) return
+    const onDown = (event: PointerEvent) => {
+      if (!root.current?.contains(event.target as Node)) setOpen(false)
+    }
+    document.addEventListener("pointerdown", onDown)
+    // Focus the first item once the menu is in the DOM.
+    const frame = requestAnimationFrame(() => root.current?.querySelector<HTMLElement>("[role=menuitem]")?.focus())
+    return () => {
+      document.removeEventListener("pointerdown", onDown)
+      cancelAnimationFrame(frame)
+    }
+  }, [open])
+
+  const copyPage = () => copy(() => pageMarkdown(props, resolver))
+  const here = typeof location === "undefined" ? "" : location.href
+  const target = props.markdownUrl ? absolute(props.markdownUrl) : props.pageUrl ?? here
+  const ask = (props.prompt ?? defaultPrompt)(target)
+
+  const viewMarkdown = async () => {
+    const text = await pageMarkdown(props, resolver)
+    const url = URL.createObjectURL(new Blob([text], { type: "text/plain;charset=utf-8" }))
+    window.open(url, "_blank", "noopener")
+    setTimeout(() => URL.revokeObjectURL(url), 60_000)
+  }
+
+  const all: MenuItem[] = [
+    { id: "copy", icon: <CopyIcon copied={false} />, label: "Copy as Markdown", hint: "Copy this page for LLMs", run: () => void copyPage() },
+    props.markdownUrl
+      ? { id: "view", icon: <FileText width={15} height={15} aria-hidden="true" />, label: "View as Markdown", hint: "Open the page as plain text", href: props.markdownUrl }
+      : { id: "view", icon: <FileText width={15} height={15} aria-hidden="true" />, label: "View as Markdown", hint: "Open the page as plain text", run: () => void viewMarkdown() },
+    { id: "chatgpt", icon: <OpenAIGlyph />, label: "Open in ChatGPT", hint: "Ask questions about this page", href: `https://chatgpt.com/?hints=search&q=${encodeURIComponent(ask)}` },
+    { id: "claude", icon: <AnthropicGlyph />, label: "Open in Claude", hint: "Ask questions about this page", href: `https://claude.ai/new?q=${encodeURIComponent(ask)}` },
+  ]
+  const wanted = props.actions ?? ["copy", "view", "chatgpt", "claude"]
+  const items = wanted.map((id) => all.find((item) => item.id === id)).filter((item): item is MenuItem => !!item)
+
+  const close = (refocus = true) => {
+    setOpen(false)
+    if (refocus) trigger.current?.focus()
+  }
+
+  const onMenuKey = (event: KeyboardEvent<HTMLDivElement>) => {
+    const entries = [...event.currentTarget.querySelectorAll<HTMLElement>("[role=menuitem]")]
+    const index = entries.indexOf(document.activeElement as HTMLElement)
+    let next = -1
+    if (event.key === "ArrowDown") next = (index + 1) % entries.length
+    else if (event.key === "ArrowUp") next = (index - 1 + entries.length) % entries.length
+    else if (event.key === "Home") next = 0
+    else if (event.key === "End") next = entries.length - 1
+    else if (event.key === "Escape") {
+      event.preventDefault()
+      close()
+      return
+    } else if (event.key === "Tab") {
+      close(false)
+      return
+    }
+    if (next < 0) return
+    event.preventDefault()
+    entries[next]?.focus()
+  }
+
+  return (
+    <div ref={root} className={props.className ? `docs-page-actions ${props.className}` : "docs-page-actions"}>
+      <button type="button" className="docs-page-actions-main" onClick={() => void copyPage()} aria-label="Copy page as Markdown">
+        <CopyIcon copied={copied} size={13} />
+        <span aria-live="polite">{copied ? "Copied" : "Copy page"}</span>
+      </button>
+      <button
+        ref={trigger}
+        type="button"
+        className="docs-page-actions-more"
+        aria-label="More page actions"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? menuId : undefined}
+        onClick={() => setOpen((value) => !value)}
+        onKeyDown={(event) => {
+          if (event.key === "ArrowDown" && !open) {
+            event.preventDefault()
+            setOpen(true)
+          }
+        }}
+      >
+        <ChevronDown width={13} height={13} strokeWidth={2.4} aria-hidden="true" className={open ? "docs-page-actions-caret-open" : undefined} />
+      </button>
+      <AnimatePresence>
+        {open ? (
+          <motion.div
+            id={menuId}
+            role="menu"
+            aria-label="Page actions"
+            className="docs-page-actions-menu"
+            onKeyDown={onMenuKey}
+            initial={reduced ? { opacity: 0 } : { opacity: 0, scale: 0.95, y: -4 }}
+            animate={{ opacity: 1, scale: 1, y: 0, transition: reduced ? { duration: 0.1 } : { type: "spring", bounce: 0.2, duration: 0.32 } }}
+            exit={{ opacity: 0, scale: reduced ? 1 : 0.97, transition: { duration: 0.12 } }}
+            style={{ transformOrigin: "top right" }}
+          >
+            {items.map((item) => {
+              const body = (
+                <>
+                  <span className="docs-page-actions-icon">{item.icon}</span>
+                  <span className="docs-page-actions-text">
+                    <span className="docs-page-actions-label">
+                      {item.label}
+                      {item.href ? <ArrowUpRight width={12} height={12} aria-hidden="true" /> : null}
+                    </span>
+                    <span className="docs-page-actions-hint">{item.hint}</span>
+                  </span>
+                </>
+              )
+              return item.href ? (
+                <a key={item.id} role="menuitem" tabIndex={-1} className="docs-page-actions-item" href={item.href} target="_blank" rel="noreferrer" onClick={() => close(false)}>
+                  {body}
+                </a>
+              ) : (
+                <button key={item.id} type="button" role="menuitem" tabIndex={-1} className="docs-page-actions-item" onClick={() => { item.run?.(); close() }}>
+                  {body}
+                </button>
+              )
+            })}
+          </motion.div>
+        ) : null}
+      </AnimatePresence>
+    </div>
+  )
+}
+
+function absolute(url: string): string {
+  if (typeof location === "undefined") return url
+  try {
+    return new URL(url, location.href).toString()
+  } catch {
+    return url
+  }
+}

package/src/docs/controls.tsx

@@ -0,0 +1,138 @@
+/* Small accessible controls shared by the demo viewer, tabs and page actions: a pill tab strip
+   (tabs semantics, roving focus) and a segmented radio group. */
+import { useId, type KeyboardEvent, type ReactNode } from "react"
+import { motion, useReducedMotion } from "framer-motion"
+
+export interface PillOption<T extends string> {
+  id: T
+  label: ReactNode
+  /** Accessible name when `label` is not plain text. */
+  ariaLabel?: string
+}
+
+const SPRING = { type: "spring", bounce: 0.18, duration: 0.45 } as const
+
+/** Arrow/Home/End move focus (and selection) across a row of buttons. */
+export function rovingKeyDown<T extends string>(
+  event: KeyboardEvent<HTMLElement>,
+  ids: readonly T[],
+  current: T,
+  select: (id: T) => void,
+  orientation: "horizontal" | "vertical" = "horizontal",
+) {
+  const prev = orientation === "horizontal" ? "ArrowLeft" : "ArrowUp"
+  const next = orientation === "horizontal" ? "ArrowRight" : "ArrowDown"
+  const index = ids.indexOf(current)
+  let target = -1
+  if (event.key === prev) target = (index - 1 + ids.length) % ids.length
+  else if (event.key === next) target = (index + 1) % ids.length
+  else if (event.key === "Home") target = 0
+  else if (event.key === "End") target = ids.length - 1
+  if (target < 0) return
+  event.preventDefault()
+  select(ids[target])
+  const buttons = event.currentTarget.querySelectorAll<HTMLElement>("[data-roving]")
+  buttons[target]?.focus()
+}
+
+/** A tab strip with a sliding pill. `panelId(id)` wires aria-controls when the panels exist. */
+export function PillTabs<T extends string>({
+  options,
+  value,
+  onChange,
+  label,
+  panelId,
+  tabId,
+  className,
+}: {
+  options: readonly PillOption<T>[]
+  value: T
+  onChange: (id: T) => void
+  label: string
+  panelId?: (id: T) => string
+  tabId?: (id: T) => string
+  className?: string
+}) {
+  const layoutId = useId()
+  const reduced = useReducedMotion()
+  return (
+    <div
+      className={className ? `docs-pills ${className}` : "docs-pills"}
+      role="tablist"
+      aria-label={label}
+      onKeyDown={(event) => rovingKeyDown(event, options.map((o) => o.id), value, onChange)}
+    >
+      {options.map((option) => {
+        const selected = option.id === value
+        return (
+          <button
+            key={option.id}
+            id={tabId?.(option.id)}
+            type="button"
+            role="tab"
+            data-roving=""
+            aria-selected={selected}
+            aria-controls={panelId?.(option.id)}
+            aria-label={option.ariaLabel}
+            tabIndex={selected ? 0 : -1}
+            className="docs-pill"
+            onClick={() => onChange(option.id)}
+          >
+            {selected ? (
+              <motion.span layoutId={`pill-${layoutId}`} className="docs-pill-indicator" transition={reduced ? { duration: 0 } : SPRING} />
+            ) : null}
+            <span className="docs-pill-label">{option.label}</span>
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+/** A segmented single choice (radio semantics), styled like the pill tabs. */
+export function Segmented<T extends string>({
+  options,
+  value,
+  onChange,
+  label,
+  className,
+}: {
+  options: readonly PillOption<T>[]
+  value: T
+  onChange: (id: T) => void
+  label: string
+  className?: string
+}) {
+  const layoutId = useId()
+  const reduced = useReducedMotion()
+  return (
+    <div
+      className={className ? `docs-pills docs-segmented ${className}` : "docs-pills docs-segmented"}
+      role="radiogroup"
+      aria-label={label}
+      onKeyDown={(event) => rovingKeyDown(event, options.map((o) => o.id), value, onChange)}
+    >
+      {options.map((option) => {
+        const selected = option.id === value
+        return (
+          <button
+            key={option.id}
+            type="button"
+            role="radio"
+            data-roving=""
+            aria-checked={selected}
+            aria-label={option.ariaLabel}
+            tabIndex={selected ? 0 : -1}
+            className="docs-pill"
+            onClick={() => onChange(option.id)}
+          >
+            {selected ? (
+              <motion.span layoutId={`seg-${layoutId}`} className="docs-pill-indicator" transition={reduced ? { duration: 0 } : SPRING} />
+            ) : null}
+            <span className="docs-pill-label">{option.label}</span>
+          </button>
+        )
+      })}
+    </div>
+  )
+}

package/src/docs/copy.tsx

@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState } from "react"
+import { Check, Copy } from "lucide-react"
+
+/** Copies text, falling back to a selection copy where the Clipboard API is unavailable. */
+export async function copyText(text: string): Promise<void> {
+  try {
+    await navigator.clipboard.writeText(text)
+  } catch {
+    const area = document.createElement("textarea")
+    area.value = text
+    area.setAttribute("readonly", "")
+    area.style.cssText = "position:fixed;top:0;left:0;opacity:0"
+    document.body.appendChild(area)
+    area.select()
+    document.execCommand("copy")
+    area.remove()
+  }
+}
+
+/**
+ * Copies text that is still being produced. Hands the clipboard a pending
+ * ClipboardItem synchronously so Safari keeps the click's user activation.
+ */
+export async function copyLazyText(produce: () => string | Promise<string>): Promise<void> {
+  const pending = Promise.resolve().then(produce)
+  if (typeof ClipboardItem !== "undefined" && navigator.clipboard?.write) {
+    try {
+      const blob = pending.then((text) => new Blob([text], { type: "text/plain" }))
+      await navigator.clipboard.write([new ClipboardItem({ "text/plain": blob })])
+      return
+    } catch {
+      // fall through to writeText / selection copy
+    }
+  }
+  await copyText(await pending)
+}
+
+/** `copied` flips true for a moment after `copy()`. */
+export function useCopied(ms = 1600) {
+  const [copied, setCopied] = useState(false)
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  useEffect(() => () => clearTimeout(timer.current), [])
+  const copy = async (text: string | (() => string | Promise<string>)) => {
+    if (typeof text === "function") await copyLazyText(text)
+    else await copyText(text)
+    setCopied(true)
+    clearTimeout(timer.current)
+    timer.current = setTimeout(() => setCopied(false), ms)
+  }
+  return { copied, copy }
+}
+
+export function CopyIcon({ copied, size = 14 }: { copied: boolean; size?: number }) {
+  return copied ? (
+    <Check className="docs-copy-icon docs-copy-icon-done" width={size} height={size} strokeWidth={2.4} aria-hidden="true" />
+  ) : (
+    <Copy className="docs-copy-icon" width={size} height={size} strokeWidth={2} aria-hidden="true" />
+  )
+}
+
+export interface CopyButtonProps {
+  text: string | (() => string | Promise<string>)
+  label?: string
+  className?: string
+}
+
+/** Icon button that copies `text` and swaps to a tick. */
+export function CopyButton({ text, label = "Copy code", className }: CopyButtonProps) {
+  const { copied, copy } = useCopied()
+  return (
+    <button
+      type="button"
+      className={className ? `docs-copy ${className}` : "docs-copy"}
+      onClick={() => void copy(text)}
+      aria-label={copied ? "Copied" : label}
+      title={copied ? "Copied" : label}
+      data-copied={copied || undefined}
+    >
+      <CopyIcon copied={copied} />
+    </button>
+  )
+}

package/src/docs/tabs-sync.ts

@@ -0,0 +1,61 @@
+import { useCallback, useSyncExternalStore } from "react"
+
+/* Page-wide (and cross-page) memory for `{% tabs sync="key" %}`: the last tab title a reader chose
+   for a key, shared by every synced tab set and persisted in localStorage. */
+
+const PREFIX = "docstream:tabs:"
+const memory = new Map<string, string>()
+const listeners = new Set<() => void>()
+
+function storage(): Storage | null {
+  try {
+    return typeof window === "undefined" ? null : window.localStorage
+  } catch {
+    return null
+  }
+}
+
+export function getSyncedTab(key: string): string | null {
+  if (memory.has(key)) return memory.get(key)!
+  const saved = storage()?.getItem(PREFIX + key) ?? null
+  if (saved !== null) memory.set(key, saved)
+  return saved
+}
+
+export function setSyncedTab(key: string, title: string): void {
+  memory.set(key, title)
+  try {
+    storage()?.setItem(PREFIX + key, title)
+  } catch {
+    // storage full or disabled: the in-memory choice still syncs this page
+  }
+  listeners.forEach((listener) => listener())
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener)
+  const onStorage = (event: StorageEvent) => {
+    if (event.key?.startsWith(PREFIX)) {
+      memory.delete(event.key.slice(PREFIX.length))
+      listener()
+    }
+  }
+  if (typeof window !== "undefined") window.addEventListener("storage", onStorage)
+  return () => {
+    listeners.delete(listener)
+    if (typeof window !== "undefined") window.removeEventListener("storage", onStorage)
+  }
+}
+
+/** `[title, setTitle]` for a sync key; both are inert when `key` is undefined. */
+export function useSyncedTab(key: string | undefined): [string | null, (title: string) => void] {
+  const title = useSyncExternalStore(
+    subscribe,
+    () => (key ? getSyncedTab(key) : null),
+    () => null,
+  )
+  const set = useCallback((next: string) => {
+    if (key) setSyncedTab(key, next)
+  }, [key])
+  return [title, set]
+}

package/src/gitbook/ast.ts

@@ -89,6 +89,11 @@ export interface TabNode {
 export interface TabsNode {
   type: "tabs"
   tabs: TabNode[]
+  /**
+   * Sync group (`{% tabs sync="pm" %}`). Every tab set with the same key follows
+   * the reader's last choice (matched by tab title), remembered across pages.
+   */
+  sync?: string
 }
 
 export interface ExpandableNode {
@@ -143,6 +148,35 @@ export interface SourceRefNode {
   title?: string
 }
 
+export type DemoLayout = "auto" | "single" | "multi"
+export type DemoViewport = "desktop" | "tablet" | "phone"
+
+export interface DemoVariantOption {
+  id: string
+  label: string
+}
+
+/**
+ * A file-backed live demo: `{% demo src="<page>/<example>" %}`. The example
+ * folder (resolved by the host's `DemoResolver`) is the authority for the
+ * component, its source files, and its defaults; attributes here override the
+ * folder's `meta.json`.
+ */
+export interface DemoNode {
+  type: "demo"
+  /** `<page>/<example>` folder id understood by the host's resolver. */
+  src: string
+  title?: string
+  description?: string
+  /** Preview height, kept verbatim (`"420"`, `"60vh"`, `"auto"`). */
+  height?: string
+  layout?: DemoLayout
+  /** `variants="full:Full,compact:Compact"`. */
+  variants?: DemoVariantOption[]
+  /** Initial preview viewport for the multi-file viewer. */
+  viewport?: DemoViewport
+}
+
 export interface ColumnNode {
   type: "column"
   children: Block[]
@@ -227,6 +261,7 @@ export type Block =
   | EmbedNode
   | ContentRefNode
   | SourceRefNode
+  | DemoNode
   | ColumnsNode
   | FigureNode
   | ListNode

package/src/gitbook/index.ts

@@ -1,6 +1,6 @@
 // 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 { parseMarkdown, parseBlocks, trimPartialInlineToken } from "./parse"
+export { parseDemoVariants, parseMarkdown, parseBlocks, trimPartialInlineToken } from "./parse"
 export { serializeBlocks, serializeMarkdown } from "./serialize"
 export { footnoteDefinitions, parseInline, plainText, refDefinitions, serializeInline, serializeReference } from "./inline"

package/src/gitbook/parse.ts

@@ -1,6 +1,10 @@
 import type {
   Block,
   ColumnNode,
+  DemoLayout,
+  DemoNode,
+  DemoVariantOption,
+  DemoViewport,
   DocumentNode,
   HintStyle,
   Inline,
@@ -155,6 +159,39 @@ export function parseMarkdown(src: string): DocumentNode {
   return doc
 }
 
+const DEMO_LAYOUTS: DemoLayout[] = ["auto", "single", "multi"]
+const DEMO_VIEWPORTS: DemoViewport[] = ["desktop", "tablet", "phone"]
+
+/** `"full:Full,compact:Compact"` → `[{ id: "full", label: "Full" }, …]`. A bare id is its own label. */
+export function parseDemoVariants(raw: string): DemoVariantOption[] {
+  return raw
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => {
+      const colon = part.indexOf(":")
+      if (colon < 0) return { id: part, label: part }
+      const id = part.slice(0, colon).trim()
+      const label = part.slice(colon + 1).trim()
+      return { id, label: label || id }
+    })
+    .filter((v) => v.id)
+}
+
+function parseDemoTag(attrs: Record<string, string>): DemoNode {
+  const variants = attrs.variants ? parseDemoVariants(attrs.variants) : []
+  return {
+    type: "demo",
+    src: (attrs.src ?? "").trim(),
+    ...(attrs.title ? { title: attrs.title } : {}),
+    ...(attrs.description ? { description: attrs.description } : {}),
+    ...(attrs.height ? { height: attrs.height } : {}),
+    ...((DEMO_LAYOUTS as string[]).includes(attrs.layout) ? { layout: attrs.layout as DemoLayout } : {}),
+    ...(variants.length ? { variants } : {}),
+    ...((DEMO_VIEWPORTS as string[]).includes(attrs.viewport) ? { viewport: attrs.viewport as DemoViewport } : {}),
+  }
+}
+
 // Strips an in-progress inline token (`[^1`, `@bre`, a lone `#`, a trailing
 // `\`) from the end of a partially streamed document so chips don't flash as
 // plain text mid-stream. No-op inside an unterminated code fence.
@@ -162,6 +199,8 @@ export function trimPartialInlineToken(md: string): string {
   const fences = md.match(/^\s*(?:```|~~~)/gm)
   if (fences && fences.length % 2 === 1) return md
   return md
+    // A block tag still arriving (`{% demo src="butt`) would flash as a paragraph.
+    .replace(/(^|\n)[ \t]*\{(?:%(?:(?!%\})[^\n])*)?$/, "$1")
     .replace(/\[\^[^\]]*$/, "")
     .replace(/(^|[\s([{])[@#][\w.-]*$/, "$1")
     .replace(/\\$/, "")
@@ -206,7 +245,7 @@ export function parseBlocks(lines: string[]): Block[] {
 
       if (tag.name === "tabs") {
         const { body, next } = collectUntil(lines, i + 1, "tabs")
-        blocks.push({ type: "tabs", tabs: parseTabs(body) })
+        blocks.push({ type: "tabs", tabs: parseTabs(body), ...(tag.attrs.sync ? { sync: tag.attrs.sync } : {}) })
         i = next
         continue
       }
@@ -288,6 +327,14 @@ export function parseBlocks(lines: string[]): Block[] {
         continue
       }
 
+      if (tag.name === "demo") {
+        blocks.push(parseDemoTag(tag.attrs))
+        i++
+        // tolerate an optional {% enddemo %}
+        if (i < lines.length && templateTag(lines[i])?.name === "enddemo") i++
+        continue
+      }
+
       if (tag.name === "updates") {
         const { body, next } = collectUntil(lines, i + 1, "updates")
         blocks.push({

package/src/gitbook/serialize.ts

@@ -50,7 +50,7 @@ function serializeBlock(b: Block): string {
       return `{% hint style="${b.style}" %}\n${serializeBlocks(b.children)}\n{% endhint %}`
 
     case "tabs":
-      return `{% tabs %}\n${b.tabs
+      return `{% tabs${b.sync ? ` sync="${b.sync}"` : ""} %}\n${b.tabs
         .map((t) => `{% tab title="${t.title}" %}\n${serializeBlocks(t.children)}\n{% endtab %}`)
         .join("\n\n")}\n{% endtabs %}`
 
@@ -92,6 +92,21 @@ function serializeBlock(b: Block): string {
       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}"` : "",
+        b.variants?.length
+          ? ` variants="${b.variants.map((v) => (v.label === v.id ? v.id : `${v.id}:${v.label}`)).join(",")}"`
+          : "",
+        b.viewport ? ` viewport="${b.viewport}"` : "",
+      ].join("")
+      return `{% demo${attrs} %}`
+    }
+
     case "columns":
       return `{% columns %}\n${b.columns
         .map((c) => `{% column %}\n${serializeBlocks(c.children)}\n{% endcolumn %}`)