Skip to content

feat: support hidden lines in example code blocks#802

Merged
crowlKats merged 1 commit into
mainfrom
feat/hidden-example-code-lines
Jun 3, 2026
Merged

feat: support hidden lines in example code blocks#802
crowlKats merged 1 commit into
mainfrom
feat/hidden-example-code-lines

Conversation

@crowlbot

@crowlbot crowlbot commented Jun 2, 2026

Copy link
Copy Markdown
Contributor

Implements hideable lines in example code blocks, à la rustdoc's documentation tests.

Closes denoland/deno#21574.

Behavior

Within a JavaScript/TypeScript example code block:

  • A line beginning with # (hash + space), or consisting solely of #, is hidden from the rendered documentation.
  • A line beginning with ## is an escape and renders as a single leading #.
# import { assertEquals } from "@std/assert";
const result = add(1, 2);
assertEquals(result, 3);

renders as:

const result = add(1, 2);
assertEquals(result, 3);

This lets authors keep boilerplate (imports, setup) runnable in doc tests (deno test --doc already strips these markers) without cluttering the rendered output.

Notes / design choices

  • Hidden lines are removed from the displayed code in both the HTML renderer and the terminal printer. In the HTML output they are retained in the copy button's data-copy so copied snippets still execute as written.
  • Processing is intentionally limited to JS/TS code-block languages (ts, js, tsx, mts, …). Other blocks (e.g. shell snippets that legitimately begin a line with #) are rendered verbatim. Happy to widen/narrow this set if preferred.
  • Shebang lines (#!) and private fields (#x, no following space) are left untouched.

Tests

Added unit tests for the line-processing helper, the terminal printer, and the HTML renderer. Existing snapshot tests are unaffected. cargo test, cargo fmt -- --check, and cargo clippy --all-targets -- -D clippy::all all pass.

Lines in JavaScript/TypeScript example code blocks that begin with `# `
(or consist solely of `#`) are now hidden from rendered documentation,
mirroring rustdoc's documentation-test behavior. A leading `##` is an
escape for a literal `#`. Hidden lines are removed from the displayed
code (both HTML and terminal output) but retained in the HTML copy
button so copied snippets remain runnable.

Processing is limited to JS/TS code blocks so that other snippets (e.g.
shell examples that legitimately begin a line with `#`) are unaffected.
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@crowlKats crowlKats merged commit 64a834e into main Jun 3, 2026
6 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: hideable doc comment codeblock lines

3 participants