Guides authoring and review of Twoslash-powered TypeScript docs examples, including hidden setup, type queries, completions, diagnostics, and multi-file snippets. Use when writing or reviewing `ts twoslash` fences or when docs examples need `
Use for docs examples powered by Twoslash.
// @errors: ... when the error itself is part of the lesson.// @noErrors only when the snippet is intentionally incomplete for some other reason, such as completion demos.// @filename: for multi-file context instead of explaining missing imports in prose.// @showEmit only when the emitted JS, .d.ts, or map file is the teaching target.^?, ^|, and ^^^ always apply to the previous line.// ^|; use uv run scripts/inspect-markers.py <file> or another column-aware tool to count columns.@filename: stays visible unless you cut it away on purpose.@showEmittedFile is only meaningful together with @showEmit.What does the user need?
├─ Show an inferred type or resolved symbol
│ └─ references/notations.md -> query markers
├─ Show autocomplete or highlight a span
│ └─ references/notations.md -> query markers
├─ Hide setup, fixtures, or boilerplate
│ └─ references/patterns.md -> hidden-setup patterns
├─ Model multiple files or fake imports
│ └─ references/patterns.md -> multi-file patterns
├─ Show or validate diagnostics
│ └─ references/notations.md -> error flags
├─ Show emitted JS / .d.ts / source maps
│ └─ references/notations.md -> emit flags
└─ Explain provenance or edge options
└─ references/source-index.md
@errors over blanket suppression.^? for inferred or resolved types.^| for completion lists; pair with @noErrors when the expression is intentionally unfinished.^^^ for visual emphasis, not semantic explanation.---cut--- or ---cut-before--- to hide setup above the visible snippet.---cut-after--- or ---cut-start--- / ---cut-end--- to hide trailing or middle noise.@filename: to create virtual files, including fake node_modules/@types shims.| Task | Files to read |
|---|---|
| New to Twoslash authoring | SKILL.md -> references/notations.md -> references/patterns.md |
| Pick the right directive | references/notations.md |
| Copy a known-good shape | references/examples.md |
| Hide fixtures or multi-file setup | references/patterns.md |
| Explain lesser-used options or provenance | references/source-index.md |
| Do a wider upstream docs sweep | example-docs.txt -> references/source-index.md |
| Run or inspect evals | evals/README.md -> |
| Script | Purpose |
|---|---|
scripts/run-evals.py | Runs response-quality evals and trigger checks against the Twoslash skill |
scripts/inspect-markers.py | Prints real line/column counts for ^?, ^^^, ^| markers. (NOTE: IN , ^| THE SLASH IN FRONT OF THE PIPE IS ONLY HERE FOR MARKDOWN ESCAPING) |
| File | Purpose |
|---|---|
references/notations.md | Exact notation names, flags, and when to use them |
references/examples.md | Small copy-paste examples for common Twoslash patterns |
references/patterns.md | Authoring defaults, hidden-setup patterns, and review checklist |
references/source-index.md | Upstream source URLs and provenance notes |
example-docs.txt | Local gitingest snapshot of upstream Twoslash docs |
evals/README.md | How to run the regression harness and read its outputs |
scripts/run-evals.py| Check marker alignment | scripts/inspect-markers.py |
| Review a noisy or broken snippet | references/patterns.md -> references/notations.md |