Racket

scribble-tools🔗ℹ

Jens Axel Søgaard <jensaxel@soegaard.net>

This library provides Scribble forms for typesetting CSS, C, C++, CSV, HTML, Java, JavaScript, JSON, Go, Haskell, LaTeX, Makefile, Markdown, Mathematica, Objective-C, plist, Python, Racket, Rhombus, Rust, shell scripts (Bash/Zsh/PowerShell), Swift, TeX, TSV, WebAssembly (WAT), YAML, and Scribble snippets with syntax coloring.

The inline forms (css-code, c-code, cpp-code, csv-code, go-code, html-code, java-code, js-code, json-code, haskell-code, latex-code, makefile-code, markdown-code, mathematica-code, objc-code, pascal-code, plist-code, python-code, racket-code, rhombus-code, rust-code, shell-code, swift-code, tex-code, tsv-code, wasm-code, yaml-code, and scribble-code) produce content.

The block forms (cssblock, cblock, cppblock, csvblock, htmlblock, goblock, javablock, jsblock, jsonblock, markdownblock, haskellblock, latexblock, makefileblock, mathematicablock, objcblock, pascalblock, plistblock, pythonblock, racketblock, rhombusblock, rustblock, shellblock, swiftblock, texblock, tsvblock, wasmblock, yamlblock, and scribbleblock) produce code blocks with optional line numbers, file labels, and escapes.

1 Guide🔗ℹ

This section gives a practical introduction to the forms and the most useful options.

1.1 Inline Forms🔗ℹ

Use inline forms when you want code inside running text:

Language		Scribble Form
CSS		@css-code{.card { color: #c33; }}
C		@c-code{int answer = 42;}
C++		@cpp-code{std::vector<int> xs = {1, 2, 3};}
CSV		@csv-code["name,age"]
Go		@go-code{func add(x int, y int) int { return x + y }}
HTML		@html-code{<button class="primary">Save</button>}
Java		@java-code{class Example { void run() { System.out.println("hi"); } }}
JavaScript		@js-code{const total = items.reduce((a, b) => a + b, 0);}
JSON		@json-code["{\"name\": \"Ada\"}"]
Haskell		@haskell-code{sumSquares xs = sum (map (^ (2 :: Int)) xs)}
LaTeX		@latex-code{\section{Intro}}
Makefile		@makefile-code{all: build test}
Markdown		@markdown-code["# Hello"]
Mathematica		@mathematica-code{f[x_] := Module[{y = x^2}, y + 1]}
Objective-C		@objc-code{@"Hello"}
Pascal		@pascal-code{function Add(x, y: Integer): Integer; begin Add := x + y; end;}
plist		@plist-code{<plist/>}
Python		@python-code{def total(xs): return sum(xs)}
Racket		@racket-code{(define (add x y) (+ x y))}
Rhombus		@rhombus-code{fun add(x, y): x + y}
Shell		@shell-code[#:shell 'bash]{if [ -f ~/.zshrc ]; then echo ok; fi}
Rust		@rust-code{let xs: Vec<i32> = vec![1, 2, 3];}
Swift		@swift-code{let answer = 42}
TeX		@tex-code{\hbox{Hello}}
TSV		@tsv-code["name\tage"]
WebAssembly		@wasm-code{(module (func (result i32) (i32.const 42)))}
YAML		@yaml-code["name: Ada"]
Scribble		@scribble-code{"@bold{Hello} world."}

Language		Result
CSS		.card { color: #c33; }
C		int answer = 42;
C++		std::vector<int> xs = {1, 2, 3};
CSV		name,age
Go		func add(x int, y int) int { return x + y }
HTML		<button class="primary">Save</button>
Java		class Example { void run() { System.out.println("hi"); } }
JavaScript		const total = items.reduce((a, b) => a + b, 0);
JSON		{"name": "Ada"}
Haskell		sumSquares xs = sum (map (^ (2 :: Int)) xs)
LaTeX		\section{Intro}
Makefile		all: build test
Markdown		# Hello
Mathematica		f[x_] := Module[{y = x^2}, y + 1]
Objective-C		Hello
Pascal		function Add(x, y: Integer): Integer; begin Add := x + y; end;
plist		<plist/>
Python		def total(xs): return sum(xs)
Racket		(define (add x y) (+ x y))
Rhombus		fun add(x, y): x + y
Shell		if [ -f ~/.zshrc ]; then echo ok; fi
Rust		let xs: Vec<i32> = vec![1, 2, 3];
Swift		let answer = 42
TeX		\hbox{Hello}
TSV		name age
WebAssembly		(module (func (result i32) (i32.const 42)))
YAML		name: Ada
Scribble		@bold{Hello} world.

The #:context option and current-scribble-context parameter are accepted for compatibility. Scribble snippets are tokenized directly by scribble-tools instead of by Scribble’s typeset-code context.

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

@bold{Hello} world.

1.2 Block Forms🔗ℹ

Use block forms for larger snippets:

CSS form
Scribble source
@cssblock{
/* Accent color */
.card {
color: #c33;
border-radius: 12px;
}
}

Rendered result
/* Accent color */
.card {
color: #c33;
border-radius: 12px;
}

HTML form
Scribble source
@htmlblock{

<main id="hero">
<h1>Hello</h1>
<p>Welcome</p>
</main>
}

Rendered result

<main id="hero">
<h1>Hello</h1>
<p>Welcome</p>
</main>

JavaScript form
Scribble source
@jsblock{
/* loadData :: () => Promise<any> */
async function loadData() {
const r = await fetch("/api/data");
return r.json();
}
}

Rendered result
/* loadData :: () => Promise<any> */
async function loadData() {
const r = await fetch("/api/data");
return r.json();
}

Python form
Scribble source
@pythonblock{
# normalize one name
def normalize_name(name):
cleaned = name.strip().title()
return cleaned or "Anonymous"
}

Rendered result
# normalize one name
def normalize_name(name):
cleaned = name.strip().title()
return cleaned or "Anonymous"

WebAssembly form
Scribble source
@wasmblock{
;; A simple module
(module
(func $fortytwo (result i32)
i32.const 42))
}

Rendered result
;; A simple module
(module
(func $fortytwo (result i32)
i32.const 42))

Shell form
Scribble source
@shellblock[#:shell 'zsh]{
# zsh bootstrap
setopt prompt_subst
autoload -Uz compinit
compinit
}

Rendered result
# zsh bootstrap
setopt prompt_subst
autoload -Uz compinit
compinit

Scribble form
Scribble source
@scribbleblock[#:context #'here]{
@@section{Greeting}
@@bold{Hello}, Scribble!
}

Rendered result
@section{Greeting}
@bold{Hello}, Scribble!

1.3 Block Form Decorations🔗ℹ

Use these options to add decorations to block output:

Scribble source

Rendered result

Line numbers
@cssblock[#:line-numbers 1]{
.card {
color: #c33;
}
}

Rendered result
1 .card {
2 color: #c33;
3 }
.card { color: #c33; }

File name
@cssblock[#:file "styles.css"]{
.card {
color: #c33;
}
}

Rendered result
"styles.css"
.card {
color: #c33;
}
.card { color: #c33; }

Line numbers + file name
@cssblock[#:line-numbers 1 #:file "styles.css"]{
.card {
color: #c33;
}
}

Rendered result
"styles.css"
1 .card {
2 color: #c33;
3 }
.card { color: #c33; }

Highlighted lines
@cssblock[#:line-numbers 1 #:highlight-lines '(2)]{
.card {
color: #c33;
}
}

Rendered result
1 .card {
2 color: #c33;
3 }
.card { color: #c33; }

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

1.5 Escapes🔗ℹ

All forms support escapes to splice Scribble content:

Scribble source

@cssblock[#:escape unq
          ".notice { color: "
          (unq (bold "tomato"))
          "; }"]

Rendered result

.notice { color: tomato; }
.notice { color: ; }

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 Go language keywords, predeclared identifiers, and selected standard-library identifiers (for example func, nil, and Println) are linked to the official Go spec and package documentation.
Common Java language keywords and standard-library identifiers (for example class, String, System, and @Override) are linked to the official Oracle Java Language Specification and Java SE API docs.
Common LaTeX commands and environments (for example \section, \label, \begin{itemize}) are linked to the LaTeX2e reference manual at latexref.xyz, while TikZ commands used inside LaTeX snippets (for example \draw) are linked to tikz.dev.
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.

1.7 Plain HTML and SXML🔗ℹ

The Scribble forms are the primary interface for manuals, but the same tokenization and linking pipeline can also generate ordinary HTML or SXML for use in a normal web page.

1.7.1 HTML strings🔗ℹ

Use code->html for inline snippets and code-block->html for block snippets. These functions return strings, so they fit directly into ordinary HTML page generation.

#lang racket/base
(require scribble-tools/html)

(define snippet
  (code-block->html 'js
                    #:line-numbers 1
                    "const n = 42;\nconsole.log(n);\n"))

(define page
  (string-append
   "<!doctype html><html><head>"
   (code-html-support)
   "</head><body>"
   snippet
   "</body></html>"))

When a page uses block snippets, copy buttons, CSS previews, font previews, or other interactive decorations, include code-html-support once in the page’s head. The support string contains the styles and JavaScript used by the generated markup.

1.7.2 SXML values🔗ℹ

Use code->sxml and code-block->sxml when you want to compose the generated markup as data before serializing it. These functions return SXML-shaped values:

#lang racket/base
(require scribble-tools/html)

(define body
  `(main
    (h1 "Renderer demo")
    (p "Inline: " ,(code->sxml 'racket "(add1 n)"))
    ,(code-block->sxml 'python
                       #:line-numbers 1
                       "def total(xs):\n    return sum(xs)\n")))

(define head
  `(head
    (meta ((charset "utf-8")))
    ,@(code-html-support-sxml)))

The convenience HTML functions are equivalent to rendering through this SXML format and serializing the result.

Use code->scribble and code-block->scribble when a program needs Scribble values from computed source text instead of using forms such as css-code and cssblock.

Escapes in the HTML/SXML API are explicit: pass strings for ordinary source, raw-sxml to splice SXML, or raw-html to splice trusted raw HTML during serialization. Use raw-sxml with the SXML API and raw-html when a pre-rendered HTML fragment must pass through the HTML serializer unchanged. Arbitrary Scribble elements are still supported by the Scribble forms, but are rejected by the HTML/SXML renderer.

2 Reference🔗ℹ

This section documents each form and procedure in detail.

2.1 Inline Forms🔗ℹ

2.1.1 Web Languages🔗ℹ

syntax
(css-code maybe-option ... str-expr ...+)

maybe-option =
| #:color-swatch? color-swatch?-expr
| #:font-preview? font-preview?-expr
| #:dimension-preview? dimension-preview?-expr
| #:mdn-links? mdn-links?-expr
| #:preview-mode preview-mode-expr
| #:preview-tooltips? preview-tooltips?-expr
| #:preview-css-url preview-css-url-expr
| #:escape escape-id

Typesets the concatenated strings as inline CSS code. Newlines and surrounding whitespace are collapsed to single spaces.

#: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; }

syntax
(html-code maybe-escape str-expr ...+)

maybe-escape =
| #:mdn-links? mdn-links?-expr
| #:escape escape-id

Typesets the concatenated strings as inline HTML code. Newlines and surrounding whitespace are collapsed to single spaces.

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>

syntax
(js-code maybe-escape str-expr ...+)

maybe-escape =
| #:jsx? jsx?-expr
| #:mdn-links? mdn-links?-expr
| #:escape escape-id

Typesets the concatenated strings as inline JavaScript code. Newlines and surrounding whitespace are collapsed to single spaces.

#: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;

2.1.2 Programming Languages🔗ℹ

syntax
(c-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline C code.

Common C keywords and standard library identifiers are linked to cppreference. The bundled identifier map was generated in 2026.

Example: int answer = 42;

syntax
(cpp-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline C++ code.

Common C++ keywords and standard library identifiers are linked to cppreference. The bundled identifier map was generated in 2026.

Example: std::vector<int> xs = {1, 2, 3};

syntax
(go-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Go code.

Common Go language keywords, predeclared identifiers, and selected standard-library identifiers are linked to the official Go spec and package documentation.

Example: func add(x int, y int) int { return x + y }

syntax
(objc-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Objective-C code.

Example: Hello

syntax
(haskell-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Haskell code.

Example: sumSquares xs = sum (map (^ (2 :: Int)) xs)

syntax
(java-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Java code.

Common Java language keywords and selected standard-library identifiers are linked to the official Oracle Java Language Specification and Java SE API documentation.

Example: class Example { void run() { System.out.println("hi"); } }

syntax
(mathematica-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Mathematica / Wolfram Language code.

Example: f[x_] := Module[{y = x^2}, y + 1]

syntax
(pascal-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Pascal code.

Pascal snippets link language-reference entries and bundled Free Pascal API identifiers from the official Free Pascal documentation.

Example: function Add(x, y: Integer): Integer; begin Add := x + y; end;

syntax
(python-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Python code. Newlines and surrounding whitespace are collapsed to single spaces.

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

Example: def answer(): return 42

syntax
(racket-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Racket code.

Example: (define (add x y) (+ x y))

syntax
(rhombus-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Rhombus code.

Example: fun add(x, y): x + y

syntax
(swift-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Swift code.

Example: let answer = 42

syntax
(rust-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Rust code.

Common Rust keywords, standard library types and traits, and common macros such as vec! and println! are linked to the official Rust documentation site at doc.rust-lang.org.

Example: let xs: Vec<i32> = vec![1, 2, 3];

syntax
(wasm-code maybe-escape str-expr ...+)

maybe-escape =
| #:docs-source docs-source-expr
| #:escape escape-id

Typesets the concatenated strings as inline WebAssembly text (WAT) code. Newlines and surrounding whitespace are collapsed to single spaces.

#: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)))

2.1.3 Document Languages🔗ℹ

syntax
(latex-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline LaTeX code. Common LaTeX commands and environments are linked to the LaTeX2e reference manual at latexref.xyz, and TikZ commands used inside LaTeX snippets are linked to tikz.dev.

Example: \section{Intro}

syntax
(markdown-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Markdown.

Example: # Hello

syntax
(scribble-code maybe-options str-expr ...+)

maybe-options =
| #:context context-expr
| #:escape escape-id

Typesets the concatenated strings as inline Scribble source code. Newlines and surrounding whitespace are collapsed to single spaces.

#: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.

syntax
(tex-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline TeX code.

Example: \hbox{Hello}

2.1.4 Tooling and Config🔗ℹ

syntax
(makefile-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline Makefile code.

Example: all: build test

syntax
(json-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline JSON.

Example: {"name": "Ada"}

syntax
(plist-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline plist XML.

Example: <plist/>

syntax
(shell-code maybe-options str-expr ...+)

maybe-options =
| #:shell shell-expr
| #:docs-source docs-source-expr
| #:escape escape-id

Typesets the concatenated strings as inline shell code. Newlines and surrounding whitespace are collapsed to single spaces.

#: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

syntax
(tsv-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline TSV text.

Example: name age

syntax
(yaml-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline YAML.

Example: name: Ada

2.1.5 Data Formats🔗ℹ

syntax
(csv-code maybe-escape str-expr ...+)

maybe-escape =
| #:escape escape-id

Typesets the concatenated strings as inline CSV text.

Example: name,age

2.2 Block Forms🔗ℹ

All block forms accept #:highlight-lines. The value is #f or a list of one-based source line numbers and inclusive ranges such as (2 . 4) or (list 2 4).

2.2.1 Web Languages🔗ℹ

syntax
(cssblock option ... str-expr ...+)

option = #:indent indent-expr
| #:line-numbers line-number-expr
| #:highlight-lines highlight-lines-expr
| #:line-number-sep line-number-sep-expr
| #:copy-button? copy-button?-expr
| #:color-swatch? color-swatch?-expr
| #:font-preview? font-preview?-expr
| #:dimension-preview? dimension-preview?-expr
| #:mdn-links? mdn-links?-expr
| #:preview-mode preview-mode-expr
| #:preview-tooltips? preview-tooltips?-expr
| #:preview-css-url preview-css-url-expr
| #:file filename-expr
| #:escape escape-id

   indent-expr : exact-nonnegative-integer?
   line-number-expr : (or/c #f exact-nonnegative-integer?)
   highlight-lines-expr : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
   line-number-sep-expr : exact-nonnegative-integer?

Typesets CSS as a block inset using 'code-inset. Options:

#:indent controls left indentation in spaces (default: 0).
#:line-numbers enables line numbers when not #f, using the given start number (default: #f).
#:highlight-lines highlights one-based source lines. Use integers for individual lines or inclusive ranges such as (2 . 4) or (list 2 4) (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; }

syntax
(cssblock0 option ... str-expr ...+)

Like cssblock, but without the inset wrapper.

Example:

.compact {
color: #444;
}
.compact { color: #444; }

syntax
(htmlblock option ... str-expr ...+)

option = #:indent indent-expr
| #:line-numbers line-number-expr
| #:highlight-lines highlight-lines-expr
| #:line-number-sep line-number-sep-expr
| #:copy-button? copy-button?-expr
| #:mdn-links? mdn-links?-expr
| #:file filename-expr
| #:escape escape-id

   indent-expr : exact-nonnegative-integer?
   line-number-expr : (or/c #f exact-nonnegative-integer?)
   highlight-lines-expr : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
   line-number-sep-expr : exact-nonnegative-integer?

Typesets HTML as a block inset using 'code-inset. Options:

#:indent controls left indentation in spaces (default: 0).
#:line-numbers enables line numbers when not #f, using the given start number (default: #f).
#:highlight-lines highlights one-based source lines. Use integers for individual lines or inclusive ranges such as (2 . 4) or (list 2 4) (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>

syntax
(htmlblock0 option ... str-expr ...+)

Like htmlblock, but without the inset wrapper.

Example:

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

syntax
(jsblock option ... str-expr ...+)

option = #:indent indent-expr
| #:line-numbers line-number-expr
| #:highlight-lines highlight-lines-expr
| #:line-number-sep line-number-sep-expr
| #:copy-button? copy-button?-expr
| #:jsx? jsx?-expr
| #:mdn-links? mdn-links?-expr
| #:file filename-expr
| #:escape escape-id

   indent-expr : exact-nonnegative-integer?
   line-number-expr : (or/c #f exact-nonnegative-integer?)
   highlight-lines-expr : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
   line-number-sep-expr : exact-nonnegative-integer?

Typesets JavaScript as a block inset using 'code-inset. Options:

#:indent controls left indentation in spaces (default: 0).
#:line-numbers enables line numbers when not #f, using the given start number (default: #f).
#:highlight-lines highlights one-based source lines. Use integers for individual lines or inclusive ranges such as (2 . 4) or (list 2 4) (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();

syntax
(jsblock0 option ... str-expr ...+)

Like jsblock, but without the inset wrapper.

Example:

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

2.2.2 Programming Languages🔗ℹ

syntax
(cblock option ... str-expr ...+)

Typesets C as a block inset.

Example:

"demo.c"
int main(void) {
return 0;
}
int main(void) { return 0; }

syntax
(cblock0 option ... str-expr ...+)

Like cblock, but without the inset wrapper.

syntax
(cppblock option ... str-expr ...+)

Typesets C++ as a block inset.

syntax
(cppblock0 option ... str-expr ...+)

Like cppblock, but without the inset wrapper.

syntax
(goblock option ... str-expr ...+)

Typesets Go code as a block inset.

syntax
(goblock0 option ... str-expr ...+)

Like goblock, but without the inset wrapper.

syntax
(javablock option ... str-expr ...+)

Typesets Java code as a block inset.

syntax
(javablock0 option ... str-expr ...+)

Like javablock, but without the inset wrapper.

syntax
(mathematicablock option ... str-expr ...+)

Typesets Mathematica / Wolfram Language code as a block inset.

syntax
(mathematicablock0 option ... str-expr ...+)

Like mathematicablock, but without the inset wrapper.

syntax
(objcblock option ... str-expr ...+)

Typesets Objective-C as a block inset.

syntax
(objcblock0 option ... str-expr ...+)

Like objcblock, but without the inset wrapper.

syntax
(haskellblock option ... str-expr ...+)

Typesets Haskell as a block inset.

syntax
(haskellblock0 option ... str-expr ...+)

Like haskellblock, but without the inset wrapper.

syntax
(pascalblock option ... str-expr ...+)

Typesets Pascal as a block inset.

syntax
(pascalblock0 option ... str-expr ...+)

Like pascalblock, but without the inset wrapper.

syntax
(pythonblock option ... str-expr ...+)

option = #:indent indent-expr
| #:line-numbers line-number-expr
| #:highlight-lines highlight-lines-expr
| #:line-number-sep line-number-sep-expr
| #:copy-button? copy-button?-expr
| #:file filename-expr
| #:escape escape-id

   indent-expr : exact-nonnegative-integer?
   line-number-expr : (or/c #f exact-nonnegative-integer?)
   highlight-lines-expr : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
   line-number-sep-expr : exact-nonnegative-integer?

Typesets Python as a block inset using 'code-inset. Options:

#:indent controls left indentation in spaces (default: 0).
#:line-numbers enables line numbers when not #f, using the given start number (default: #f).
#:highlight-lines highlights one-based source lines. Use integers for individual lines or inclusive ranges such as (2 . 4) or (list 2 4) (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 def double(n):
2 return n * 2
def double(n): return n * 2

syntax
(pythonblock0 option ... str-expr ...+)

Like pythonblock, but without the inset wrapper.

Example:

def greet(name):
return f"Hello, {name}"

}

syntax
(racketblock option ... str-expr ...+)

Typesets Racket code as a block inset.

syntax
(racketblock0 option ... str-expr ...+)

Like racketblock, but without the inset wrapper.

syntax
(rhombusblock option ... str-expr ...+)

Typesets Rhombus code as a block inset.

syntax
(rhombusblock0 option ... str-expr ...+)

Like rhombusblock, but without the inset wrapper.

syntax
(swiftblock option ... str-expr ...+)

Typesets Swift code as a block inset.

syntax
(swiftblock0 option ... str-expr ...+)

Like swiftblock, but without the inset wrapper.

syntax
(rustblock option ... str-expr ...+)

Typesets Rust code as a block inset.

syntax
(rustblock0 option ... str-expr ...+)

Like rustblock, but without the inset wrapper.

syntax
(wasmblock option ... str-expr ...+)

option = #:indent indent-expr
| #:line-numbers line-number-expr
| #:highlight-lines highlight-lines-expr
| #:line-number-sep line-number-sep-expr
| #:copy-button? copy-button?-expr
| #:docs-source docs-source-expr
| #:file filename-expr
| #:escape escape-id

   indent-expr : exact-nonnegative-integer?
   line-number-expr : (or/c #f exact-nonnegative-integer?)
   highlight-lines-expr : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
   line-number-sep-expr : exact-nonnegative-integer?

Typesets WebAssembly text (WAT) as a block inset using 'code-inset. Options:

#:indent controls left indentation in spaces (default: 0).
#:line-numbers enables line numbers when not #f, using the given start number (default: #f).
#:highlight-lines highlights one-based source lines. Use integers for individual lines or inclusive ranges such as (2 . 4) or (list 2 4) (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))

syntax
(wasmblock0 option ... str-expr ...+)

Like wasmblock, but without the inset wrapper.

Example:

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

2.2.3 Document Languages🔗ℹ

syntax
(latexblock option ... str-expr ...+)

Typesets LaTeX as a block inset.

syntax
(latexblock0 option ... str-expr ...+)

Like latexblock, but without the inset wrapper.

syntax
(markdownblock option ... str-expr ...+)

Typesets Markdown as a block inset.

syntax
(markdownblock0 option ... str-expr ...+)

Like markdownblock, but without the inset wrapper.

syntax
(texblock option ... str-expr ...+)

Typesets TeX as a block inset.

syntax
(texblock0 option ... str-expr ...+)

Like texblock, but without the inset wrapper.

2.2.4 Tooling and Config🔗ℹ

syntax
(makefileblock option ... str-expr ...+)

Typesets Makefile code as a block inset.

syntax
(makefileblock0 option ... str-expr ...+)

Like makefileblock, but without the inset wrapper.

syntax
(jsonblock option ... str-expr ...+)

Typesets JSON as a block inset.

Example:

1 {
2 "name": "Ada",
3 "active": true
4 }
{ "name": "Ada", "active": true }

syntax
(jsonblock0 option ... str-expr ...+)

Like jsonblock, but without the inset wrapper.

syntax
(plistblock option ... str-expr ...+)

Typesets plist XML as a block inset.

syntax
(plistblock0 option ... str-expr ...+)

Like plistblock, but without the inset wrapper.

syntax
(shellblock option ... str-expr ...+)

option = #:shell shell-expr
| #:docs-source docs-source-expr
| #:indent indent-expr
| #:line-numbers line-number-expr
| #:highlight-lines highlight-lines-expr
| #:line-number-sep line-number-sep-expr
| #:copy-button? copy-button?-expr
| #:file filename-expr
| #:escape escape-id

   indent-expr : exact-nonnegative-integer?
   line-number-expr : (or/c #f exact-nonnegative-integer?)
   highlight-lines-expr : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
   line-number-sep-expr : exact-nonnegative-integer?

Typesets shell source as a block inset using 'code-inset. Options:

#: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).
#:highlight-lines highlights one-based source lines. Use integers for individual lines or inclusive ranges such as (2 . 4) or (list 2 4) (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

syntax
(shellblock0 option ... str-expr ...+)

Like shellblock, but without the inset wrapper.

Example:

setopt prompt_subst
autoload -Uz compinit
compinit

syntax
(yamlblock option ... str-expr ...+)

Typesets YAML as a block inset.

syntax
(yamlblock0 option ... str-expr ...+)

Like yamlblock, but without the inset wrapper.

Example:

name: Ada
active: true
name: Ada active: true

2.2.5 Data Formats🔗ℹ

syntax
(csvblock option ... str-expr ...+)

Typesets CSV as a block inset.

syntax
(csvblock0 option ... str-expr ...+)

Like csvblock, but without the inset wrapper.

syntax
(tsvblock option ... str-expr ...+)

Typesets TSV as a block inset.

syntax
(tsvblock0 option ... str-expr ...+)

Like tsvblock, but without the inset wrapper.

parameter
(current-wasm-docs-source) → (or/c 'wasm-spec-3.0 'mdn 'none)
(current-wasm-docs-source src) → void?
src : (or/c 'wasm-spec-3.0 'mdn 'none)

Controls the default documentation source used by wasm-code, wasmblock, and wasmblock0 when #:docs-source is not provided. The default value is 'wasm-spec-3.0.

parameter
(current-scribble-shell) → (or/c 'bash 'zsh 'powershell 'pwsh)
(current-scribble-shell sh) → void?
sh : (or/c 'bash 'zsh 'powershell 'pwsh)

Controls the default shell flavor used by shell-code, shellblock, and shellblock0 when #:shell is not provided. The default value is 'bash.

parameter
(current-shell-docs-source)
→ (or/c 'auto 'bash 'zsh 'powershell 'pwsh 'posix 'none)
(current-shell-docs-source src) → void?
src : (or/c 'auto 'bash 'zsh 'powershell 'pwsh 'posix 'none)

Controls the default shell documentation source used by shell-code, shellblock, and shellblock0 when #:docs-source is not provided. The default value is 'auto, which means: use Bash docs when the effective shell is 'bash, Zsh docs when the effective shell is 'zsh, and PowerShell docs when the effective shell is 'powershell (or 'pwsh). To force one source regardless of shell selection, use 'bash, 'zsh, 'powershell, 'posix, or 'none.

parameter
(current-scribble-context) → (or/c #f syntax?)
(current-scribble-context ctx) → void?
ctx : (or/c #f syntax?)

Controls the default syntax context used by scribble-code, scribbleblock, and scribbleblock0 when #:context is not provided. The default value is #f. }

syntax
(scribbleblock option ... str-expr ...+)

option = #:indent indent-expr
| #:line-numbers line-number-expr
| #:highlight-lines highlight-lines-expr
| #:line-number-sep line-number-sep-expr
| #:lang lang-expr
| #:context context-expr
| #:copy-button? copy-button?-expr
| #:file filename-expr
| #:escape escape-id

   indent-expr : exact-nonnegative-integer?
   line-number-expr : (or/c #f exact-nonnegative-integer?)
   highlight-lines-expr : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
   line-number-sep-expr : exact-nonnegative-integer?
   lang-expr : string?
   context-expr : (or/c #f syntax?)

Typesets Scribble source as a block inset using 'code-inset.

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).
#:highlight-lines highlights one-based source lines. Use integers for individual lines or inclusive ranges such as (2 . 4) or (list 2 4) (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:

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

syntax
(scribbleblock0 option ... str-expr ...+)

Like scribbleblock, but without the inset wrapper.

Example:

@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
}

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 HTML, SXML, and Scribble Renderers🔗ℹ

(require scribble-tools/html)

package: scribble-tools

Use this module when you want the same code-snippet rendering outside the language-specific Scribble forms. It provides three output families:

HTML strings, via code->html and code-block->html, for ordinary web pages;
SXML values, via code->sxml and code-block->sxml, for composing markup as data;
Scribble values, via code->scribble and code-block->scribble, for callers that need a renderer procedure instead of a form.

All six rendering procedures take a lang symbol followed by one or more source values. Recognized language symbols are 'css, 'c, 'cpp, 'csv, 'go, 'html, 'java, 'js, 'json, 'haskell, 'latex, 'makefile, 'markdown, 'mathematica, 'objc, 'pascal, 'plist, 'python, 'racket, 'rhombus, 'rust, 'swift, 'tex, 'tsv, 'wasm, 'yaml, 'scribble, 'bash, 'zsh, and 'powershell. The symbol 'pwsh is accepted as an alias for 'powershell, and 'shell selects (current-scribble-shell). Other symbols are accepted, but render as plain text without language-specific coloring or documentation links.

For the HTML and SXML procedures, each value must be one of:

a string, which contributes source text;
(raw-sxml v), which splices v as SXML;
(raw-html s), which carries trusted pre-rendered HTML through serialization.

For the Scribble procedures, string values contribute source text and non-string values are spliced as Scribble content.

procedure
(code->html lang
[ #:color-swatch? color-swatch?
#:font-preview? font-preview?
#:dimension-preview? dimension-preview?
#:mdn-links? mdn-links?
#:docs-source docs-source
#:preview-tooltips? preview-tooltips?
#:preview-mode preview-mode
#:preview-css-url preview-css-url
#:jsx? jsx?]
value ...) → string?
  lang : symbol?
  color-swatch? : boolean? = #t
  font-preview? : boolean? = #t
  dimension-preview? : boolean? = #t
  mdn-links? : boolean? = #t
  docs-source : any/c = #f
  preview-tooltips? : boolean? = #t
  preview-mode : symbol? = 'always
  preview-css-url : (or/c #f string?) = #f
  jsx? : boolean? = #f
  value : (or/c string? raw-sxml? raw-html?)

Renders an inline code snippet as an HTML string. Include code-html-support in the page when the snippet may contain previews or other generated support markup.

The optional keyword arguments control inline rendering:

#:color-swatch? enables CSS color and gradient previews when supported by the language.
#:font-preview? enables CSS font-family previews when supported by the language.
#:dimension-preview? enables compact spacing, radius, and similar numeric-value previews.
#:mdn-links? controls documentation links for recognized identifiers.
#:docs-source selects the documentation source for languages with more than one link map, such as shell and WebAssembly snippets.
#:preview-tooltips? controls tooltip attributes on generated preview elements.
#:preview-mode selects when previews are emitted; 'always emits them in the generated markup.
#:preview-css-url supplies an optional stylesheet URL used by previews that need page CSS context.
#:jsx? treats JavaScript snippets as JSX when lang is 'js.

procedure
(code-block->html lang
[ #:file filename
#:indent indent
#:line-numbers line-numbers
#:line-number-sep line-number-sep
#:highlight-lines highlight-lines
#:copy-button? copy-button?
#:color-swatch? color-swatch?
#:font-preview? font-preview?
#:dimension-preview? dimension-preview?
#:mdn-links? mdn-links?
#:docs-source docs-source
#:preview-tooltips? preview-tooltips?
#:preview-mode preview-mode
#:preview-css-url preview-css-url
#:jsx? jsx?
#:inset? inset?]
value ...)
→ string?
  lang : symbol?
  filename : (or/c #f string?) = #f
  indent : exact-nonnegative-integer? = 0
  line-numbers : (or/c #f exact-integer?) = #f
  line-number-sep : exact-nonnegative-integer? = 1
   highlight-lines : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
= #f
  copy-button? : boolean? = #t
  color-swatch? : boolean? = #t
  font-preview? : boolean? = #t
  dimension-preview? : boolean? = #t
  mdn-links? : boolean? = #t
  docs-source : any/c = #f
  preview-tooltips? : boolean? = #t
  preview-mode : symbol? = 'always
  preview-css-url : (or/c #f string?) = #f
  jsx? : boolean? = #f
  inset? : boolean? = #t
  value : (or/c string? raw-sxml? raw-html?)

Renders a block code snippet as an HTML string.

The block-specific keyword arguments control the surrounding block:

#:file adds a file label when given a string; #f disables the label.
#:indent adds leading indentation to the displayed block.
#:line-numbers starts line numbering at the given integer; #f disables line numbers.
#:line-number-sep controls the space between line numbers and source text.
#:highlight-lines highlights one-based source lines. The list may contain individual line numbers, inclusive dotted-pair ranges such as (2 . 4), and inclusive two-element ranges such as (list 2 4). Highlighting is independent of the number passed to #:line-numbers.
#:copy-button? controls whether generated markup includes copy-button support for the block source.
#:inset? controls whether the block is visually wrapped like a Scribble code block.

The remaining keyword arguments have the same meanings as in code->html.

procedure
(code->sxml lang
[ #:color-swatch? color-swatch?
#:font-preview? font-preview?
#:dimension-preview? dimension-preview?
#:mdn-links? mdn-links?
#:docs-source docs-source
#:preview-tooltips? preview-tooltips?
#:preview-mode preview-mode
#:preview-css-url preview-css-url
#:jsx? jsx?]
value ...) → any/c
  lang : symbol?
  color-swatch? : boolean? = #t
  font-preview? : boolean? = #t
  dimension-preview? : boolean? = #t
  mdn-links? : boolean? = #t
  docs-source : any/c = #f
  preview-tooltips? : boolean? = #t
  preview-mode : symbol? = 'always
  preview-css-url : (or/c #f string?) = #f
  jsx? : boolean? = #f
  value : (or/c string? raw-sxml? raw-html?)

Renders an inline code snippet as an SXML value. The result may contain raw-html values when the input includes trusted raw HTML escapes; serialize it with the same serializer used by code->html. The keyword arguments have the same meanings as in code->html.

procedure
(code-block->sxml lang
[ #:file filename
#:indent indent
#:line-numbers line-numbers
#:line-number-sep line-number-sep
#:highlight-lines highlight-lines
#:copy-button? copy-button?
#:color-swatch? color-swatch?
#:font-preview? font-preview?
#:dimension-preview? dimension-preview?
#:mdn-links? mdn-links?
#:docs-source docs-source
#:preview-tooltips? preview-tooltips?
#:preview-mode preview-mode
#:preview-css-url preview-css-url
#:jsx? jsx?
#:inset? inset?]
value ...)
→ any/c
  lang : symbol?
  filename : (or/c #f string?) = #f
  indent : exact-nonnegative-integer? = 0
  line-numbers : (or/c #f exact-integer?) = #f
  line-number-sep : exact-nonnegative-integer? = 1
   highlight-lines : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
= #f
  copy-button? : boolean? = #t
  color-swatch? : boolean? = #t
  font-preview? : boolean? = #t
  dimension-preview? : boolean? = #t
  mdn-links? : boolean? = #t
  docs-source : any/c = #f
  preview-tooltips? : boolean? = #t
  preview-mode : symbol? = 'always
  preview-css-url : (or/c #f string?) = #f
  jsx? : boolean? = #f
  inset? : boolean? = #t
  value : (or/c string? raw-sxml? raw-html?)

Renders a block code snippet as an SXML value. It accepts the same block and language-specific keyword options as code-block->html, with the same meanings.

procedure
(code-html-support) → string?

Returns the CSS and JavaScript support string used by the generated HTML renderer output. Include it once in the page’s head.

procedure
(code-html-support-sxml) → list?

Returns the CSS and JavaScript support nodes as SXML.

procedure
(code->scribble lang
[ #:color-swatch? color-swatch?
#:font-preview? font-preview?
#:dimension-preview? dimension-preview?
#:mdn-links? mdn-links?
#:docs-source docs-source
#:preview-tooltips? preview-tooltips?
#:preview-mode preview-mode
#:preview-css-url preview-css-url
#:jsx? jsx?]
value ...)
→ any/c
  lang : symbol?
  color-swatch? : boolean? = #t
  font-preview? : boolean? = #t
  dimension-preview? : boolean? = #t
  mdn-links? : boolean? = #t
  docs-source : any/c = #f
  preview-tooltips? : boolean? = #t
  preview-mode : symbol? = 'always
  preview-css-url : (or/c #f string?) = #f
  jsx? : boolean? = #f
  value : any/c

Renders an inline code snippet as a Scribble value. String values are tokenized as source text; non-string values are spliced into the resulting Scribble content. The keyword arguments have the same meanings as in code->html, except that Scribble values are produced instead of HTML strings.

procedure
(code-block->scribble lang
[ #:file filename
#:indent indent
#:line-numbers line-numbers
#:line-number-sep line-number-sep
#:highlight-lines highlight-lines
#:copy-button? copy-button?
#:color-swatch? color-swatch?
#:font-preview? font-preview?
#:dimension-preview? dimension-preview?
#:mdn-links? mdn-links?
#:docs-source docs-source
#:preview-tooltips? preview-tooltips?
#:preview-mode preview-mode
#:preview-css-url preview-css-url
#:jsx? jsx?
#:inset? inset?]
value ...)
→ any/c
  lang : symbol?
  filename : (or/c #f string?) = #f
  indent : exact-nonnegative-integer? = 0
  line-numbers : (or/c #f exact-integer?) = #f
  line-number-sep : exact-nonnegative-integer? = 1
   highlight-lines : (or/c #f (listof (or/c exact-positive-integer? (cons/c exact-positive-integer? exact-positive-integer?) (list/c exact-positive-integer? exact-positive-integer?))))
= #f
  copy-button? : boolean? = #t
  color-swatch? : boolean? = #t
  font-preview? : boolean? = #t
  dimension-preview? : boolean? = #t
  mdn-links? : boolean? = #t
  docs-source : any/c = #f
  preview-tooltips? : boolean? = #t
  preview-mode : symbol? = 'always
  preview-css-url : (or/c #f string?) = #f
  jsx? : boolean? = #f
  inset? : boolean? = #t
  value : any/c

Renders a block code snippet as a Scribble value. It accepts the same block and language-specific keyword options as code-block->html. String values are tokenized as source text; non-string values are spliced into the resulting Scribble content.

procedure
(raw-sxml value) → raw-sxml?
value : any/c

Wraps value so the SXML renderer splices it as markup.

procedure
(raw-sxml? value) → boolean?
value : any/c

Recognizes values produced by raw-sxml.

procedure
(raw-html value) → raw-html?
value : string?

Wraps trusted HTML so the HTML serializer emits it without escaping.

procedure
(raw-html? value) → boolean?
value : any/c

Recognizes values produced by raw-html.

2.5 YouTube Embeds🔗ℹ

(require scribble-tools/youtube)

package: scribble-tools

Use this module when a Scribble document needs to embed a YouTube video. The generated iframe uses the standard YouTube embedded-player URL shape, https://www.youtube.com/embed/VIDEO_ID. YouTube documents that embedded players should have a viewport of at least 200px by 200px, so smaller dimensions are rejected.

procedure
(youtube video
[ #:title title
#:width width
#:height height
#:start start
#:params params
#:privacy-enhanced? privacy-enhanced?
#:allow allow
#:allow-fullscreen? allow-fullscreen?]) → block?
  video : (or/c string? symbol?)
  title : string? = "YouTube video player"
  width : exact-positive-integer? = 640
  height : exact-positive-integer? = 360
  start : (or/c #f exact-nonnegative-integer?) = #f
   params :
(listof (cons/c (or/c symbol? string?)
                 (or/c string? symbol? number? boolean?)))
= null
  privacy-enhanced? : boolean? = #f
   allow : string?
= "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  allow-fullscreen? : boolean? = #t

Produces a Scribble block containing a YouTube iframe.

The video argument may be an 11-character YouTube video id or a common YouTube URL such as a watch?v=..., youtu.be/..., /embed/..., /shorts/..., or /live/... URL.

Use #:start for the standard YouTube player start parameter, given in seconds. Use #:params for additional player parameters; boolean values are serialized as 1 and 0. Use #:privacy-enhanced? to generate a www.youtube-nocookie.com embed URL instead of www.youtube.com.

#lang racket/base
(require scribble-tools/youtube)

(youtube "https://www.youtube.com/watch?v=lw6TaiXzHAE"
         #:title "Example video"
         #:width 640
         #:height 360
         #:start 30
         #:params '((rel . 0)))

Rendered result:

If you open the generated HTML directly as a file:// URL, YouTube may show Error 153 with the message Video player configuration error. Serve the page through a local or remote web server instead.

2.6 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.

procedure
(mdn-map-path) → path?

Returns the user override map path used by #:mdn-links? in CSS/HTML/JavaScript forms. If the file exists, entries in it override bundled defaults.

procedure
(mdn-default-map-entries)
→ (listof (list/c symbol? symbol? string? string?))

Returns bundled compact default entries as (list lang class token url-or-path) records. In addition to explicit entries, the resolver also supports implicit coverage for all CSS property names (Web/CSS/<property>), all known HTML element tags (Web/HTML/Element/<tag>), and common WebAssembly instruction families (WebAssembly/Reference/...).

procedure
(mdn-entry? v) → boolean?
v : any/c

Recognizes one map entry record.

procedure
(mdn-install-map! entries-or-path) → path?
entries-or-path :
(or/c path-string?
(listof (list/c symbol? symbol? string? string?)))

Installs a user override map. You can pass either a list of entries or the path to a .rktd file containing such a list.

procedure
(mdn-reset-map!) → boolean?

Deletes the user override map (if present), reverting to bundled defaults. Returns #t when a file was removed.

procedure
(mdn-export-default-map! dest) → path-string?
dest : path-string?

Writes bundled defaults to dest as a .rktd file so it can be edited and re-installed with mdn-install-map!.

Command-line helper:

racket -l scribble-tools/mdn-map-tool -- --path

racket -l scribble-tools/mdn-map-tool -- --export-default mdn-map.rktd

racket -l scribble-tools/mdn-map-tool -- --build-default mdn-map-built.rktd

racket -l scribble-tools/mdn-map-tool -- --install mdn-map.rktd

racket -l scribble-tools/mdn-map-tool -- --update-from mdn-map-custom.rktd

racket -l scribble-tools/mdn-map-tool -- --reset

Map build pipeline (dedupe + optional merge):

racket -l scribble-tools/mdn-map-build -- --stats

racket -l scribble-tools/mdn-map-build -- --out mdn-map-built.rktd

racket -l scribble-tools/mdn-map-build -- --merge mdn-map-custom.rktd --out mdn-map-merged.rktd

racket -l scribble-tools/mdn-map-build -- --merge mdn-map-custom.rktd --install

3 Extended Examples🔗ℹ

This chapter provides longer rendered examples for each supported language. Each block uses line numbers and a file label to make lexer behavior and documentation links easier to inspect.

3.1 Web Languages🔗ℹ

3.1.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 }

3.1.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>

3.1.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();

3.2 Programming Languages🔗ℹ

3.2.1 C🔗ℹ

"extended/cache.c"
1 typedef struct {
2   const char *key;
3   int value;
4 } entry_t;
5
6 static int lookup(const entry_t *entries, int count, const char *key) {
7   for (int i = 0; i < count; ++i) {
8     if (strcmp(entries[i].key, key) == 0) {
9       return entries[i].value;
10     }
11   }
12   return -1;
13 }

3.2.2 C++🔗ℹ

"extended/cache.cpp"
1 #include <algorithm>
2 #include <string>
3 #include <vector>
4
5 struct Entry {
6   std::string title;
7   int score;
8 };
9
10 std::vector<std::string> top_titles(std::vector<Entry> entries) {
11   std::sort(entries.begin(), entries.end(),
12             [](const Entry &a, const Entry &b) { return a.score > b.score; });
13   std::vector<std::string> out;
14   for (const auto &entry : entries) out.push_back(entry.title);
15   return out;
16 }

3.2.3 Go🔗ℹ

"extended/quicksort.go"
1 package main
2
3 func quickSort(xs []int) []int {
4     if len(xs) < 2 {
5         return xs
6     }
7
8     pivot := xs[0]
9     var left, right []int
10     for _, x := range xs[1:] {
11         if x < pivot {
12             left = append(left, x)
13         } else {
14             right = append(right, x)
15         }
16     }
17
18     left = quickSort(left)
19     right = quickSort(right)
20     return append(append(left, pivot), right...)
21 }

3.2.4 Objective-C🔗ℹ

"extended/view.m"
1 #import <Foundation/Foundation.h>
2
3 @interface Greeter : NSObject
4 - (NSString *)messageFor:(NSString *)name;
5 @end
6
7 @implementation Greeter
8 - (NSString *)messageFor:(NSString *)name {
9 return [NSString stringWithFormat:@"Hello, %@", name];
10 }
11 @end

3.2.5 Haskell🔗ℹ

"extended/Stats.hs"
1 module Stats where
2
3 sumSquares :: [Int] -> Int
4 sumSquares xs = sum (map square xs)
5   where
6     square n = n * n
7
8 describe :: [Int] -> String
9 describe xs =
10   "count=" ++ show (length xs) ++ ", total=" ++ show (sum xs)

3.2.6 Java🔗ℹ

"extended/QuickSort.java"
1 class QuickSort {
2     static void quickSort(int[] xs, int lo, int hi) {
3         if (lo >= hi) {
4             return;
5         }
6
7         int pivot = xs[(lo + hi) / 2];
8         int i = lo;
9         int j = hi;
10
11         while (i <= j) {
12             while (xs[i] < pivot) {
13                 i++;
14             }
15             while (xs[j] > pivot) {
16                 j--;
17             }
18             if (i <= j) {
19                 int tmp = xs[i];
20                 xs[i] = xs[j];
21                 xs[j] = tmp;
22                 i++;
23                 j--;
24             }
25         }
26
27         quickSort(xs, lo, j);
28         quickSort(xs, i, hi);
29     }
30 }

3.2.7 Mathematica🔗ℹ

"extended/helpers.wl"
1 ClearAll[quickStats];
2
3 quickStats[xs_List] := Module[
4     {sorted = Sort[xs], total = Total[xs]},
5     <|
6         "count" -> Length[xs],
7         "min" -> First[sorted],
8         "max" -> Last[sorted],
9         "mean" -> N[total/Length[xs], 4]
10     |>
11 ]

3.2.8 Pascal🔗ℹ

"extended/helpers.pas"
1 function Factorial(n: Integer): Integer;
2 begin
3   if n <= 1 then
4     Factorial := 1
5   else
6     Factorial := n * Factorial(n - 1);
7 end;

3.2.9 Python🔗ℹ

"extended/report.py"
1 from dataclasses import dataclass
2
3
4 @dataclass
5 class Entry:
6     title: str
7     score: int
8
9
10 def top_entries(rows, limit=3):
11     ranked = sorted(rows, key=lambda row: row.score, reverse=True)
12     return [entry.title for entry in ranked[:limit] if entry.score >= 0]
13
14
15 def format_report(rows):
16     titles = top_entries(rows)
17     if not titles:
18         return "no entries"
19     return ", ".join(titles)

3.2.10 Racket🔗ℹ

"extended/helpers.rkt"
1 (define (group-by-length words)
2   (for/fold ([ht (hash)])
3             ([word (in-list words)])
4     (define len (string-length word))
5     (hash-update ht len (lambda (xs) (cons word xs)) '())))
6
7 (group-by-length '("css" "html" "scribble"))

3.2.11 Rhombus🔗ℹ

"extended/helpers.rhm"
1 fun summarize(name, count):
2   if count == 1:
3     "$name has 1 item"
4   else:
5     "$name has $(count) items"

3.2.12 Swift🔗ℹ

"extended/helpers.swift"
1 struct Entry {
2   let title: String
3   let score: Int
4 }
5
6 func topTitles(_ entries: [Entry], limit: Int = 3) -> [String] {
7   entries
8     .sorted { $0.score > $1.score }
9     .prefix(limit)
10     .map(\.title)
11 }

3.2.13 Rust🔗ℹ

"extended/helpers.rs"
1 use std::collections::HashMap;
2
3 fn histogram(words: &[&str]) -> HashMap<String, usize> {
4     let mut counts = HashMap::new();
5     for word in words {
6         *counts.entry((*word).to_string()).or_insert(0) += 1;
7     }
8     counts
9 }

3.2.14 WebAssembly🔗ℹ

"extended/module.wat"
1 (module
2   (memory (export "mem") 1)
3   (func $sum_to_acc (param $i i32) (param $n i32) (param $acc i32) (result i32)
4     (if (result i32) (i32.le_s (local.get $i) (local.get $n))
5       (then
6         (call $sum_to_acc
7           (i32.add (local.get $i) (i32.const 1))
8           (local.get $n)
9           (i32.add (local.get $acc) (local.get $i))))
10       (else
11         (local.get $acc))))
12   (func (export "sum_to") (param $n i32) (result i32)
13     (call $sum_to_acc (i32.const 0) (local.get $n) (i32.const 0))))

3.3 Document Languages🔗ℹ

3.3.1 LaTeX🔗ℹ

"extended/doc.tex"
1 \section{Overview}
2 \[
3   f(x) = x^2 + 2x + 1
4 \]
5
6 \usepackage{tikz}
7
8 \begin{tikzpicture}
9   \draw (0,0) -- (2,1);
10   \node[right] at (2,1) {Endpoint};
11 \end{tikzpicture}

3.3.2 Markdown🔗ℹ

"extended/notes.md"
1 # Release Notes
2
3 ## Highlights
4
5 - Added Python support
6 - Migrated lexers to the `lexers` package
7 - Expanded rendered examples
8
9 ```bash
10 raco test private/lang-code.rkt
11 ```
12
13 ```racket
14 (define (build-docs)
15 (displayln "scribblings/scribble-tools.scrbl"))
16 ```

3.3.3 Scribble🔗ℹ

"extended/guide.scrbl"
1 @title{Extended Scribble Example}
2 @section{Overview}
3 This paragraph includes @bold{inline formatting},
4 @italic{emphasis}, and @racket[code] references.
5 @itemlist[
6   @item{First point}
7   @item{Second point}
8   @item{Third point}
9 ]
10 @subsection{Details}
11 See @secref["reference-inline-forms"] for inline forms.

3.3.4 TeX🔗ℹ

"extended/doc.tex"
1 \def\foo#1{$$#1^2$$ \verb|x+y|}
2 \hbox{Hello}
3 \vskip 1em
4 \centerline{\foo{n}}

3.4 Tooling and Config🔗ℹ

3.4.1 Makefile🔗ℹ

"extended/Makefile"
1 APP = scribble-tools
2
3 .PHONY: docs test
4
5 all: docs test | html
6
7 docs:
8 raco scribble +m --html --dest html scribblings/scribble-tools.scrbl && printf '%s\n' done
9
10 test:
11 raco test private/lang-code.rkt
12
13 build:
14 ${CC} -o $@ $<

3.4.2 JSON🔗ℹ

"extended/config.json"
1 {
2   "name": "scribble-tools",
3   "features": {
4     "copyButton": true,
5     "lineNumbers": true,
6     "links": ["mdn", "shell-docs", "wasm-spec"]
7   },
8   "targets": ["html", "manual"]
9 }

3.4.3 plist🔗ℹ

"extended/Info.plist"
1 <?xml version="1.0" encoding="UTF-8"?>
2 <plist version="1.0">
3   <dict>
4     <key>CFBundleName</key>
5     <string>scribble-tools</string>
6     <key>CFBundleVersion</key>
7     <string>1.0</string>
8   </dict>
9 </plist>

3.4.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 "$@"

3.4.5 YAML🔗ℹ

"extended/config.yaml"
1 name: scribble-tools
2 features:
3   copy_button: true
4   line_numbers: true
5   docs_links:
6     - mdn
7     - shell-docs
8     - wasm-spec

3.5 Data Formats🔗ℹ

3.5.1 CSV and TSV🔗ℹ

"extended/people.csv"
1 name,role,active
2 Ada,author,true
3 Grace,editor,false
4 Linus,reviewer,true

"extended/people.tsv"
1 name   role      active
2 Ada    author    true
3 Grace  editor    false
4 Linus  reviewer  true