#Code Blocks

Fenced code blocks in selfdoc get automatic syntax highlighting, language labels, and a copy button. Beyond the basics, you can enable line numbers, interactive run buttons, inline annotations, diff highlighting, and automatic language tabs.

#Syntax Highlighting

selfdoc uses Pygments for build-time syntax highlighting, supporting hundreds of languages out of the box with no client-side JavaScript required. Highlighting happens during the build, so the output is static HTML with CSS classes. Just specify the language after the opening fence:

def greet(name: str) -> str: return f"Hello, {name}!"

Pygments supports hundreds of languages out of the box. If the language is not recognized, the code renders as plain text. Light and dark mode get separate Pygments styles (default/monokai) that switch automatically with the theme.

#Language Icons

Each code block with a recognized language label gets a small SVG icon next to the language name in the header bar. The icons provide a visual cue that helps readers quickly identify the language, especially in tabbed code blocks showing the same concept in multiple languages. Control the icon style with code_icons in your config:

{
  "code_icons": "colorful"
}

#Line Numbers

Enable line numbers globally or per block to help readers reference specific lines in discussions, reviews, or tutorials. Numbers are rendered via CSS counters in the gutter, so they do not get selected when a user copies code from the block. Enable globally with line_numbers in your config:

{
  "line_numbers": true
}

Line numbers appear in the gutter via CSS counters, so they are not selectable when copying code. You can also enable line numbers per block using the line_numbers annotation in your fence:

def example(): pass

Per-block annotations can also set the starting line number with line_start:

# This line is numbered 42 return result

#Run Buttons

Enable interactive run buttons that let readers execute code examples in an online playground without leaving your documentation site. When enabled, each code block with a recognized language gets a "Run" button that opens the code in an appropriate external environment. Enable globally with run_button in your config:

{
  "run_button": true
}

When enabled, code blocks get a "Run" button that opens the code in an appropriate online playground. You can also enable run buttons per block with the run annotation:

print("Hello, world!")

#Annotations

Inline annotations turn numbered comments like // [1] or # [1] into small clickable badges that reveal explanatory text on hover or focus. This lets you walk readers through code step by step without cluttering the source with long inline comments. Add annotation definitions after the closing fence:

config = load_config() # [1] result = build(config) # [2]

[1]: Reads selfdoc.json from the current directory
[2]: Resolves directives and writes HTML output

The numbered markers in the code become small badge elements. Click or focus a badge to see the annotation text. This is useful for walking through code step by step without cluttering the code itself with long comments.

#Diff Highlighting

Use the diff language identifier to get line-level add/remove coloring that visually distinguishes additions from deletions. selfdoc also auto-detects diff-style content in any code block where lines start with + or - characters. Use it to show migration steps or API changes:

-old_function() +new_function(with_args=True) unchanged_line()

Lines starting with + are highlighted green, lines starting with - are highlighted red, and lines starting with a space are neutral. selfdoc also auto-detects diff-style content in any code block where lines start with + or -.

#Code Tabs

When you place two or more fenced code blocks with different languages next to each other with no content between them, selfdoc automatically groups them into a tabbed interface. This is useful for showing the same concept in multiple languages, alternative installation methods, or platform-specific instructions. Only blocks with language labels participate in tab grouping:

pip install selfdoc

npm install -g selfdoc

This renders as a single code block with "python" and "bash" tabs. The user clicks a tab to see that version. Only blocks with language labels participate in tab grouping -- unlabeled blocks are left standalone.

#Copy Button

Every code block gets a copy-to-clipboard button automatically. No config needed. It appears in the top-right corner of the block on hover and copies the raw code content (without line numbers or annotations).

Next: Custom Directives -->