scribble-tools🔗ℹ

1.1 Inline Forms🔗ℹ

Use inline forms when you want code inside running text:

If you want scribble-code to link identifiers to their documentation, you need to provide a context. Either add "#:context #'here" when calling scribble-code, or set the context using a parameter:

@current-scribble-context[#'here]

@scribble-code["@bold{Hello} world."]

@current-scribble-context[#'here] @scribble-code["@bold{Hello} world."]

@bold{Hello} world.

1.2 Block Forms🔗ℹ

Use block forms for larger snippets:

1.3 Block Form Decorations🔗ℹ

Use these options to add decorations to block output:

1.4 Preview Visualizations🔗ℹ

css-code and cssblock can show visual helpers:

.badge {

color: #0a7;

background: linear-gradient(90deg, #0a7, #5cf);

font-family: "Fira Code", monospace;Aa

margin: 16px;

border-radius: 4px;

border-radius: 8px;

}

.badge { color: #0a7; background: linear-gradient(90deg, #0a7, #5cf); font-family: "Fira Code", monospace; margin: 16px; border-radius: 4px; border-radius: 8px; }

1.5 Escapes🔗ℹ

All forms support escapes to splice Scribble content:

1.6 Documentation Links🔗ℹ

By default, code output includes documentation links for common identifiers:

• CSS properties (for example display, grid, border-radius).

• HTML elements (for example <section>, <button>, <script>).

• Common JavaScript classes, methods, and language keywords (for example Array, querySelector, map, const).

• Common shell keywords and builtins (for example if, setopt, Get-ChildItem), linked to GNU Bash, Zsh, or PowerShell documentation.

• Common WebAssembly instructions and declarations (for example module, func, local.get, i32.add), linked to the WebAssembly Core Spec site by default.

2.1 Inline Forms🔗ℹ

#:color-swatch? controls whether detected CSS color literals are followed by a small color swatch (default: #t). Gradient literals (for example linear-gradient (...)) are shown as a small bar swatch.

#:font-preview? controls whether font-family declarations are followed by a small Aa preview in the selected font (default: #t).

#:dimension-preview? controls whether spacing and radius declarations such as margin, padding, gap, and border-radius get tiny inline visualizers (default: #t).

#:mdn-links? controls whether common CSS tokens are wrapped as hyperlinks to MDN documentation (default: #t).

#:preview-mode controls when previews are shown: 'always, 'hover, or 'none (default: 'always).

#:preview-tooltips? controls whether preview decorations expose tooltips (hover/focus) and related runtime tooltip behavior (default: #t).

#:preview-css-url optionally points to an external stylesheet for preview UI classes. When provided, the runtime loads that stylesheet instead of injecting inline preview CSS.

An optional #:escape identifier configures escapes of the form (escape-id expr) to splice expr-produced elements into the typeset output.

Example: h1 { color: #c33;  }

An optional #:escape identifier configures escapes of the form (escape-id expr) to splice expr-produced elements into the typeset output.

#:mdn-links? controls whether common HTML tokens are wrapped as hyperlinks to MDN documentation, including CSS and JavaScript tokens that appear inside <style> and <script> sections (default: #t).

Example: <em class="note">Hi</em>

#:jsx? enables JSX-aware tokenization for snippets that contain embedded tags (default: #f).

#:mdn-links? controls whether common JavaScript tokens are wrapped as hyperlinks to MDN documentation (default: #t).

An optional #:escape identifier configures escapes of the form (escape-id expr) to splice expr-produced elements into the typeset output.

Example: const n = 42;

#:shell selects shell flavor: 'bash, 'zsh, 'powershell, or 'pwsh. Default: (current-scribble-shell).

#:docs-source selects where shell documentation links point: 'auto, 'bash, 'zsh, 'powershell, 'posix, or 'none. Default: (current-shell-docs-source). When the effective value is 'auto, links follow the effective shell: 'bash when #:shell (or current-scribble-shell) is 'bash, 'zsh when it is 'zsh, and 'powershell when it is 'powershell or 'pwsh.

An optional #:escape identifier configures escapes of the form (escape-id expr) to splice expr-produced elements into the typeset output.

Example: if [ -f ~/.zshrc ]; then echo ok; fi

#:docs-source selects where WebAssembly documentation links point: 'wasm-spec-3.0, 'mdn, or 'none. The default comes from current-wasm-docs-source, which defaults to 'wasm-spec-3.0.

An optional #:escape identifier configures escapes of the form (escape-id expr) to splice expr-produced elements into the typeset output.

Example: (module (func (result i32) (i32.const 42)))

#:context supplies syntax context for identifier link resolution (default: (current-scribble-context)). Recommended: use #'here when you want identifiers in a snippet to resolve against the current manual’s for-label imports.

An optional #:escape identifier configures escapes of the form (escape-id expr) to splice expr-produced elements into the typeset output.

Example: @bold{Hi} there.

2.2 Block Forms🔗ℹ

• #:indent controls left indentation in spaces (default: 0).

• #:line-numbers enables line numbers when not #f, using the given start number (default: #f).

• #:line-number-sep controls the spacing between the line number and code (default: 1).

• #:copy-button? controls whether a copy icon appears on hover/focus to copy the block text to the clipboard (default: #t).

• #:color-swatch? controls whether detected CSS color literals are followed by a small swatch; gradient literals are shown as a small bar (default: #t).

• #:font-preview? controls whether font-family declarations are followed by a small Aa preview (default: #t).

• #:dimension-preview? controls whether spacing and radius declarations (for example margin, padding, gap, letter-spacing, text-indent, filter: blur (...), and border-radius) are followed by small visualizer decorations (default: #t).

• #:mdn-links? controls whether common CSS tokens are wrapped as hyperlinks to MDN documentation (default: #t).

• #:preview-mode controls when previews are shown: 'always, 'hover, or 'none (default: 'always).

• #:preview-tooltips? controls whether preview decorations include tooltip text and interactive hover/focus tooltip UI (default: #t).

• #:preview-css-url optionally points to an external stylesheet URL/path for preview classes; when set, runtime links that stylesheet instead of injecting inline preview CSS (default: #f).

• #:file wraps the result in filebox with filename-expr as label (default: #f, i.e. no file label).

• #:escape changes the escape identifier; subforms of the shape (escape-id expr) splice expr as content (default escape id: unsyntax).

Example:

1 .card {

2   color: #c33;

3 }

.card { color: #c33; }

Example:

.compact {

color: #444;

}

.compact { color: #444; }

• #:indent controls left indentation in spaces (default: 0).

• #:line-numbers enables line numbers when not #f, using the given start number (default: #f).

• #:line-number-sep controls the spacing between the line number and code (default: 1).

• #:copy-button? controls whether a copy icon appears on hover/focus to copy the block text to the clipboard (default: #t).

• #:mdn-links? controls whether common HTML tokens are wrapped as hyperlinks to MDN documentation, including CSS and JavaScript tokens that appear inside <style> and <script> sections (default: #t).

• #:file wraps the result in filebox with filename-expr as label (default: #f, i.e. no file label).

• #:escape changes the escape identifier; subforms of the shape (escape-id expr) splice expr as content (default escape id: unsyntax).

Example:

"snippet.html"

<main>

<p>Example</p>

</main>

<main> <p>Example</p> </main>

Example:

<ul>

<li>One</li>

<li>Two</li>

</ul>

<ul> <li>One</li> <li>Two</li> </ul>

• #:indent controls left indentation in spaces (default: 0).

• #:line-numbers enables line numbers when not #f, using the given start number (default: #f).

• #:line-number-sep controls the spacing between the line number and code (default: 1).

• #:copy-button? controls whether a copy icon appears on hover/focus to copy the block text to the clipboard (default: #t).

• #:jsx? enables JSX-aware tokenization for snippets containing embedded tags (default: #f).

• #:mdn-links? controls whether common JavaScript tokens are wrapped as hyperlinks to MDN documentation (default: #t).

• #:file wraps the result in filebox with filename-expr as label (default: #f, i.e. no file label).

• #:escape changes the escape identifier; subforms of the shape (escape-id expr) splice expr as content (default escape id: unsyntax).

Example:

console.log("escaped");

console.log();

Example:

let total = 0;

for (const n of [1, 2, 3]) {

total += n;

}

let total = 0; for (const n of [1, 2, 3]) { total += n; }

• #:shell selects shell flavor: 'bash, 'zsh, 'powershell, or 'pwsh. Default: (current-scribble-shell).

• #:docs-source selects link targets: 'auto, 'bash, 'zsh, 'powershell, 'posix, or 'none. Default: (current-shell-docs-source). With 'auto, links follow the effective shell selected by #:shell (or current-scribble-shell).

• #:indent controls left indentation in spaces (default: 0).

• #:line-numbers enables line numbers when not #f, using the given start number (default: #f).

• #:line-number-sep controls the spacing between the line number and code (default: 1).

• #:copy-button? controls whether a copy icon appears on hover/focus to copy the block text to the clipboard (default: #t).

• #:file wraps the result in filebox with filename-expr as label (default: #f, i.e. no file label).

• #:escape changes the escape identifier; subforms of the shape (escape-id expr) splice expr as content (default escape id: unsyntax).

Example:

1 # build step

2 if [ -f ./configure ]; then

3   ./configure && make

4 fi

# build step if [ -f ./configure ]; then ./configure && make fi

Example:

setopt prompt_subst

autoload -Uz compinit

compinit

setopt prompt_subst autoload -Uz compinit compinit

• #:indent controls left indentation in spaces (default: 0).

• #:line-numbers enables line numbers when not #f, using the given start number (default: #f).

• #:line-number-sep controls the spacing between the line number and code (default: 1).

• #:copy-button? controls whether a copy icon appears on hover/focus to copy the block text to the clipboard (default: #t).

• #:docs-source selects WebAssembly link targets: 'wasm-spec-3.0, 'mdn, or 'none. Default: (current-wasm-docs-source).

• #:file wraps the result in filebox with filename-expr as label (default: #f, i.e. no file label).

• #:escape changes the escape identifier; subforms of the shape (escape-id expr) splice expr as content (default escape id: unsyntax).

Example:

1 (module

2   (func (result i32)

3     i32.const 42))

(module (func (result i32) i32.const 42))

Example:

(module

(func (result i32)

i32.const 7))

(module (func (result i32) i32.const 7))

The most important option is #:context. If provided identifiers will be linked to their documentation entries. If you are using the same context several times, it can be convenient to set the parameter current-scribble-context instead of using #:context repeatedly.

Options:

• #:indent controls left indentation in spaces (default: 0).

• #:line-numbers enables line numbers when not #f, using the given start number (default: #f).

• #:line-number-sep controls the spacing between the line number and code (default: 1).

• #:lang chooses the language line used for parsing/linking when the snippet itself does not start with #lang (default: "scribble/manual").

• #:context supplies syntax context for identifier link resolution (default: (current-scribble-context)). Recommended: use #'here when you want identifiers in a snippet to resolve against the current manual’s for-label imports.

• #:copy-button? controls whether a copy icon appears on hover/focus to copy the block text to the clipboard (default: #t).

• #:file wraps the result in filebox with filename-expr as label (default: #f, i.e. no file label).

• #:escape changes the escape identifier; subforms of the shape (escape-id expr) splice expr as content (default escape id: unsyntax).

Example:

2 @title{Small Example}

3 This is @bold{Scribble} source.

4

@title{Small Example} This is @bold{Scribble} source.

Example:

@itemlist[

@item{Alpha}

@item{Beta}

]

@itemlist[ @item{Alpha} @item{Beta} ]

2.3 Preview Legend🔗ℹ

Rendered legend example:

.legend {

color: #c33;

background: linear-gradient(90deg, red, blue);

margin: 4px;

margin: 12px;

margin: 28px;

filter: blur(2px);

filter: blur(8px);

filter: blur(18px);

border-radius: 2px;

border-radius: 6px;

border-radius: 9px;

font-family: "Fira Code", monospace;Aa

font-family: "Georgia", serif;Aa

font-family: "Helvetica Neue", Arial, sans-serif;Aa

}

.legend { color: #c33; background: linear-gradient(90deg, red, blue); margin: 4px; margin: 12px; margin: 28px; filter: blur(2px); filter: blur(8px); filter: blur(18px); border-radius: 2px; border-radius: 6px; border-radius: 9px; font-family: "Fira Code", monospace; font-family: "Georgia", serif; font-family: "Helvetica Neue", Arial, sans-serif; }

• Color square: a detected color literal such as #c33 or red.

• Gradient bar: a detected gradient literal such as linear-gradient (...).

• Spacing bar: detected spacing-sized values (for example margin, gap, letter-spacing, or filter: blur (...)) scaled to a compact width.

• Radius chip: detected border-radius values, where the chip corner radius mirrors the declaration.

• Font Aa: preview of font-family, including fallback resolution tooltip and missing-font warning.

2.4 MDN Maps🔗ℹ

MDN maps control which CSS/HTML/JavaScript/WebAssembly identifiers become links to the MDN documentation site. The procedures below let you inspect the active map, install overrides, reset to defaults, and export the bundled entries. Most users will not need these tools, but they are useful when you want to add links that are not covered by the default maps.

Command-line helper:

Map build pipeline (dedupe + optional merge):

3.1 CSS🔗ℹ

"extended/styles.css"

1 :root {

2   --brand: #0b62a3;

3   --accent: oklch(66% 0.18 28);

4 }

5

6 .layout {

7   display: grid;

8   grid-template-columns: 240px 1fr;

9   gap: clamp(0.75rem, 2vw, 1.5rem);

10   margin: 16px;

11   border-radius: 9px;

12   background: linear-gradient(90deg, #f6f8fb, #eef3ff);

13 }

14

15 .button {

16   color: white;

17   background: color-mix(in srgb, var--brand(--brand) 80%, black);

18   border: 1px solid #0a4f83;

19   padding: 0.5rem 0.8rem;

20   font-family: "Fira Code", "JetBrains Mono", monospace;Aa

21 }

:root { --brand: #0b62a3; --accent: oklch(66% 0.18 28); } .layout { display: grid; grid-template-columns: 240px 1fr; gap: clamp(0.75rem, 2vw, 1.5rem); margin: 16px; border-radius: 9px; background: linear-gradient(90deg, #f6f8fb, #eef3ff); } .button { color: white; background: color-mix(in srgb, var(--brand) 80%, black); border: 1px solid #0a4f83; padding: 0.5rem 0.8rem; font-family: "Fira Code", "JetBrains Mono", monospace; }

3.2 HTML🔗ℹ

"extended/index.html"

1 <!doctype html>

2 <html lang="en">

3   <head>

4     <meta charset="utf-8">

5     <title>Extended Example</title>

6     <style>

7       .hero { color: #c33;  margin: 12px;  }

8       .hero em { font-family: "Georgia", serif;Aa }

9     </style>

10   </head>

11   <body>

12     <main id="app">

13       <h1 class="hero">Hello <em>world</em></h1>

14       <button type="button" data-role="save">Save</button>

15     </main>

16     <script>

17       const root = document.querySelector("#app");

18       if (root) root.setAttribute("data-ready", "yes");

19     </script>

20   </body>

21 </html>

<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>Extended Example</title> <style> .hero { color: #c33;#c33 margin: 12px; } .hero em { font-family: "Georgia", serif;"Georgia", serif } </style> </head> <body> <main id="app"> <h1 class="hero">Hello <em>world</em></h1> <button type="button" data-role="save">Save</button> </main> <script> const root = document.querySelector("#app"); if (root) root.setAttribute("data-ready", "yes"); </script> </body> </html>

3.3 JavaScript🔗ℹ

"extended/app.js"

1 function quickSort(xs, cmp = (a, b) => a - b) {

2   if (xs.length <= 1) return xs.slice();

3   const [pivot, ...rest] = xs;

4   const left = [];

5   const right = [];

6   for (const x of rest) {

7     if (cmp(x, pivot) < 0) left.push(x); else right.push(x);

8   }

9   return [...quickSort(left, cmp), pivot, ...quickSort(right, cmp)];

10 }

11

12 function renderNumbers(listEl, numbers) {

13   listEl.textContent = "";

14   for (const n of numbers) {

15     const li = document.createElement("li");

16     li.textContent = String(n);

17     listEl.append(li);

18   }

19 }

20

21 function parseInput(inputEl) {

22   return inputEl.value

23     .split(/[\\s,]+/)

24     .map((s) => s.trim())

25     .filter(Boolean)

26     .map(Number)

27     .filter((n) => Number.isFinite(n));

28 }

29

30 function boot() {

31   const inputEl = document.querySelector("#numbers");

32   const buttonEl = document.querySelector("#sort");

33   const listEl = document.querySelector("#result");

34   if (!inputEl || !buttonEl || !listEl) return;

35

36   buttonEl.addEventListener("click", () => {

37     const data = parseInput(inputEl);

38     const sorted = quickSort(data);

39     renderNumbers(listEl, sorted);

40   });

41 }

42

43 boot();

function quickSort(xs, cmp = (a, b) => a - b) { if (xs.length <= 1) return xs.slice(); const [pivot, ...rest] = xs; const left = []; const right = []; for (const x of rest) { if (cmp(x, pivot) < 0) left.push(x); else right.push(x); } return [...quickSort(left, cmp), pivot, ...quickSort(right, cmp)]; } function renderNumbers(listEl, numbers) { listEl.textContent = ""; for (const n of numbers) { const li = document.createElement("li"); li.textContent = String(n); listEl.append(li); } } function parseInput(inputEl) { return inputEl.value .split(/[\\s,]+/) .map((s) => s.trim()) .filter(Boolean) .map(Number) .filter((n) => Number.isFinite(n)); } function boot() { const inputEl = document.querySelector("#numbers"); const buttonEl = document.querySelector("#sort"); const listEl = document.querySelector("#result"); if (!inputEl || !buttonEl || !listEl) return; buttonEl.addEventListener("click", () => { const data = parseInput(inputEl); const sorted = quickSort(data); renderNumbers(listEl, sorted); }); } boot();

3.4 Shell🔗ℹ

This utility copies one directory tree to another and validates arguments before running the copy operation.

"extended/copy-tree.sh"

1 #!/usr/bin/env bash

2 set -euo pipefail

3

4 usage() {

5   echo "usage: $0 <source-dir> [dest-dir]"

6 }

7

8 copy_tree() {

9   local src="$1"

10   local dst="$2"

11   mkdir -p "$dst"

12   cp -R "$src"/. "$dst"/

13 }

14

15 main() {

16   if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then

17     usage

18     return 2

19   fi

20   local src="$1"

21   local dst="${2:-./out}"

22   if [ ! -d "$src" ]; then

23     echo "error: source directory not found: $src" >&2

24     return 1

25   fi

26   copy_tree "$src" "$dst"

27   echo "copied $src -> $dst"

28 }

29

30 main "$@"

#!/usr/bin/env bash set -euo pipefail usage() { echo "usage: $0 <source-dir> [dest-dir]" } copy_tree() { local src="$1" local dst="$2" mkdir -p "$dst" cp -R "$src"/. "$dst"/ } main() { if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then usage return 2 fi local src="$1" local dst="${2:-./out}" if [ ! -d "$src" ]; then echo "error: source directory not found: $src" >&2 return 1 fi copy_tree "$src" "$dst" echo "copied $src -> $dst" } main "$@"