Skip to main content
Code blocks display syntax-highlighted source code with support for annotations, focus regions, and line-by-line animations.

​
Basic Syntax

Use a code fence with the code kind and optional parameters: 
```code:hash-fn lang=ts
function hash(key: string): number {
  let h = 0
  for (const ch of key) {
    h = (h * 31 + ch.charCodeAt(0)) | 0
  }
  return h
}
---
signature: 1
init: 2
loop: 3-5
return-val: 7
```
Format: ```code:name lang=language
  • name: Unique identifier for the block (required)
  • lang: Programming language for syntax highlighting (required)

​
Supported Languages

The following languages are supported for syntax highlighting:
  • JavaScript: javascript, js
  • TypeScript: typescript, ts, tsx
  • JSX/TSX: jsx, tsx
  • Python: python, py
  • Rust: rust, rs
  • Go: go
  • Java: java
  • C/C++: c, cpp, c++
  • SQL: sql
  • Bash/Shell: bash, sh
  • Data formats: json, yaml, yml
  • Web: html, css, scss
  • Plain text: text, txt

​
Shorthand Syntax

You can use bare language tags without the code: prefix: 
```typescript
const greeting = "Hello, world!";
```
This is equivalent to: 
```code lang=typescript
const greeting = "Hello, world!";
```

​
Inline Annotations

Add floating callouts to specific lines using the // ! syntax: 
```typescript
function hash(key: string): number {
  let h = 0
  for (const ch of key) {
    h = (h * 31 + ch.charCodeAt(0)) | 0  // ! Bitwise clamp to 32-bit int
  }
  return h
}
```
The annotation text is stripped from the code display and rendered as a floating callout next to the line.

​
Regions

Define named regions to target with triggers like focus and pulse. Regions are defined in the footer section (below ---) and target specific line numbers.

​
Line Number Formats

single-line: 5
range: 3-8
multiple: 1, 4-6, 9
mixed: 1, 3-5, 8, 12-15

​
Example with Regions

```code:binary-search lang=python
def binary_search(arr, target):
    left, right = 0, len(arr) - 1
    while left <= right:
        mid = (left + right) // 2
        if arr[mid] == target:
            return mid
        elif arr[mid] < target:
            left = mid + 1
        else:
            right = mid - 1
    return -1
---
signature: 1
init: 2
loop: 3-9
mid-calc: 4
check: 5-9
found: 6
```

​
Triggers

Code blocks work with all standard triggers:
  • {{show: code-name}} - Display the code block
  • {{focus: region-name}} - Highlight specific lines (others dim)
  • {{pulse: region-name}} - Briefly emphasize lines
  • {{pan: region-name}} - Scroll to specific lines in long files
  • {{annotate: region-name "text"}} - Add floating labels to lines

​
Animation Effects

Code blocks support special animation effects:

​
Typewriter Effect

Reveal code line-by-line with a typing animation: 
{{show: implementation typewriter 2s linear}}
Best for:
  • First code reveals in a step
  • Building suspense
  • Emphasizing code construction

​
Line-Level Morphing

When transforming between two code blocks, lines animate individually: 
{{transform: version-1->version-2}}
The renderer:
  • Preserves common lines
  • Fades out removed lines
  • Slides in new lines
  • Morphs changed tokens when possible

​
Best Practices

​
Region Naming

Do: Use semantic names that describe concepts 
signature: 1
loop-body: 4-8
error-handling: 10-12
Don’t: Use positional names 
line-3: 3
top-part: 1-5
the-important-bit: 7-9

​
Code Length

  • Keep blocks under 30 lines when possible
  • Use focus and pan for longer files
  • Split complex functions into multiple steps

​
Annotations

  • Use sparingly (1-3 per block)
  • Keep text short (5-10 words)
  • Explain non-obvious details

​
Real Example

# Understanding Hash Functions

{{show: hash-fn typewriter 1.5s}} Here's a simple hash function. {{focus: init}} It starts by initializing an accumulator. {{focus: loop}} Then it iterates through each character, {{focus: hash-step}} multiplying the current hash and adding the character code. {{focus: return-val}} Finally, it returns the computed hash.

```code:hash-fn lang=typescript
function hash(key: string): number {
  let h = 0  // ! Accumulator starts at zero
  for (const ch of key) {
    h = (h * 31 + ch.charCodeAt(0)) | 0  // ! Prime multiplier reduces collisions
  }
  return h
}
---
signature: 1
init: 2
loop: 3-5
hash-step: 4
return-val: 7
```

Build docs developers (and LLMs) love

Get started for freeTalk to us