Skip to content

Commit 47fca39

Browse files
committed
docs: wrap fence-syntax demos in 4-backtick md outer fences
Markdown renderers strip the fence info string when rendering a code block, so a literal \`\`\`ts test name=\"...\"\`\`\` block in the source showed up to readers as a plain ts code block — the marker that the example was teaching was invisible. Wrap every fence-syntax demonstration in a 4-backtick md outer fence so the inner triple-backtick fence (with its info string intact) is displayed verbatim. Affects: * README.md - the 'Write a doctest' example * docs/writing-tests.md - the intro example, the auto-injected helpers example, and the imports example * docs/options.md - the name=, skip, only, and combined examples The Imports section in writing-tests.md and the Combining options section in options.md were already wrapped — converted them from the md title="example" form to the plain md form for consistency.
1 parent 78ee35a commit 47fca39

3 files changed

Lines changed: 20 additions & 9 deletions

File tree

README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,12 @@ Add `test` to any TypeScript fence in any `.md` file. The block's body becomes
1818
the body of an `it()` named after the nearest preceding heading. `describe`,
1919
`it`, and `expect` are injected for you.
2020

21+
````md
2122
```ts test
2223
import { sum } from "./sum.ts"
2324
expect(sum(1, 2)).toBe(3)
2425
```
26+
````
2527

2628
Untagged `ts` blocks render normally and are not run, so you can mix
2729
illustrative snippets and runnable assertions in the same article.

docs/options.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,11 @@ parametric options, bare tokens for booleans.
2424
Useful when the heading is too generic or you want stable names regardless of
2525
heading edits.
2626

27+
````md
2728
```ts test name="adds two positive numbers"
2829
expect(1 + 1).toBe(2)
2930
```
31+
````
3032

3133
User-supplied names are passed through verbatim — no `#1`/`#2` suffixing even
3234
on collisions.
@@ -36,27 +38,31 @@ on collisions.
3638
Marks the block so vitest/jest reports it but doesn't execute it. Useful for
3739
documenting behavior that's pending or temporarily broken.
3840

41+
````md
3942
```ts test skip
4043
// not executed
4144
```
45+
````
4246

4347
## Focusing on one test
4448

4549
Mirrors vitest/jest `it.only(...)` — only this block runs in its file; all
4650
others are skipped.
4751

52+
````md
4853
```ts test only
4954
expect(true).toBe(true)
5055
```
56+
````
5157

5258
## Combining options
5359

5460
Options can be combined freely. When both `skip` and `only` are set on the
5561
same block, `skip` wins (safer default for CI: no-op the marker rather than
5662
silently focus).
5763

58-
```md title="example"
59-
\`\`\`ts test only name="focus me"
64+
````md
65+
```ts test only name="focus me"
6066
expect(true).toBe(true)
61-
\`\`\`
6267
```
68+
````

docs/writing-tests.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,14 @@ description: Mark code blocks as runnable tests and how testdocs picks them up.
1111
Mark a code block in any `.md` file as a runnable test by adding `test` to its
1212
fence info string:
1313

14+
````md
1415
```ts test
1516
expect(1 + 1).toBe(2)
1617
```
18+
````
1719

18-
The fence above is a real test. Untagged `ts` blocks render normally and are
19-
not run, so you can freely mix illustrative snippets and runnable assertions
20-
in the same article.
20+
Untagged `ts` blocks render normally and are not run, so you can freely mix
21+
illustrative snippets and runnable assertions in the same article.
2122

2223
## Test names
2324

@@ -31,24 +32,26 @@ see [Per-block options](/options/).
3132
`describe`, `it`, and `expect` are injected at the top of the generated test
3233
module — you don't need to import them. Doctest bodies stay clean:
3334

35+
````md
3436
```ts test
3537
const items = [1, 2, 3]
3638
expect(items.length).toBe(3)
3739
```
40+
````
3841

3942
## Imports
4043

4144
Any `import` statements inside a runnable block are hoisted to the module top
4245
and shared across every test in the same `.md` file. Multi-line imports work
4346
because the parser uses a real TypeScript AST (ts-morph), not a regex.
4447

45-
```md title="example"
46-
\`\`\`ts test
48+
````md
49+
```ts test
4750
import { sum } from "./sum.ts"
4851

4952
expect(sum(1, 2)).toBe(3)
50-
\`\`\`
5153
```
54+
````
5255

5356
## Supported languages
5457

0 commit comments

Comments
 (0)