Code Blocks

Add syntax-highlighted code with Rosettes, include files, configure themes, and create multi-language examples

8 min read 1641 words

How to add syntax-highlighted code to your documentation.

Basic Code Blocks

Wrap code in triple backticks with a language identifier:

```python
def hello():
    print("Hello, World!")
```

Result:

def hello():
    print("Hello, World!")

Supported Languages

Bengal uses Rosettes for syntax highlighting—a modern, thread-safe highlighter designed for Python 3.14t free-threading. Rosettes supports 55+ languages:

Language Identifier
Python python, py
JavaScript javascript, js
TypeScript typescript, ts
Bash/Shell bash, sh, shell, zsh
YAML yaml, yml
JSON json
TOML toml
HTML html
CSS css
Markdown markdown, md
Language Identifier
Rust rust, rs
Go go, golang
C c, h
C++ cpp, c++, cxx
Zig zig
Nim nim
V v, vlang
Mojo mojo, 🔥
Language Identifier
Java java
Kotlin kotlin, kt
Scala scala, sc
Groovy groovy, gradle
Clojure clojure, clj
Language Identifier
SQL sql, mysql, postgresql
GraphQL graphql, gql
HCL/Terraform hcl, terraform, tf
Dockerfile dockerfile, docker
Nginx nginx
INI ini, cfg, conf
Protobuf protobuf, proto
Prisma prisma
CUE cue
Pkl pkl
Language Identifier
Ruby ruby, rb
PHP php
Perl perl, pl
Lua lua
R r, rlang
Julia julia, jl
Elixir elixir, ex
PowerShell powershell, ps1, pwsh
Fish fish
AWK awk, gawk
Language Identifier
SCSS/Sass scss, sass
Vue vue
Svelte svelte
Jinja2 jinja2, jinja, j2
Liquid liquid, jekyll
Handlebars handlebars, hbs
Nunjucks nunjucks, njk
Twig twig
Language Identifier
Diff diff, patch
reStructuredText rst, restructuredtext
AsciiDoc asciidoc, adoc
LaTeX latex, tex
MyST myst, mystmd
Mermaid mermaid, mmd
XML xml, xsl, svg
HTTP http, https
Regex regex, regexp
Language Identifier
Haskell haskell, hs
OCaml ocaml, ml, reasonml
Dart dart
Swift swift
WebAssembly wasm, wat
CUDA cuda, cu
Triton triton
Stan stan
Gleam gleam
Cypher cypher, neo4j

Tip

Languages not in the list are rendered as plain preformatted text with proper HTML escaping.

Line Highlighting

Draw attention to specific lines with{hl_lines="..."}:

```python {hl_lines="2"}
def hello():
    print("This line is highlighted!")
    return True
```

Highlight Multiple Lines

{hl_lines="2 4"}     # Lines 2 and 4
{hl_lines="2-5"}     # Lines 2 through 5
{hl_lines="1 3-5 8"} # Lines 1, 3-5, and 8

Line Numbers

Add line numbers for reference:

```python {linenos=true}
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
```

Start from a Specific Line

```python {linenos=true, linenostart=42}
# This starts at line 42
def important_function():
    pass
```

Include Code from Files

Useliteralincludeto include code directly from source files:

:::{literalinclude} /path/to/file.py
:language: python
:::

Include Specific Lines

:::{literalinclude} /path/to/file.py
:language: python
:start-line: 10
:end-line: 25
:::

With Line Numbers and Highlighting

:::{literalinclude} /path/to/file.py
:language: python
:linenos:
:emphasize-lines: 3,5
:::

Tip

Useliteralincludeto keep documentation in sync with actual source code. When the source changes, your docs update automatically.

Multi-Language Examples

Show the same concept in multiple languages with code tabs. Usecode-tabsfor a streamlined, code-first experience with auto-sync, language icons, and copy buttons.

Syntax

Tab labels are automatically derived from the code fence language—no extra markers needed:

:::{code-tabs}

```python
print("Hello")
```

```javascript
console.log("Hello");
```

```bash
echo "Hello"
```

:::

Result

I0:

With Filenames and Highlights

Add filenames and line highlights directly in the code fence info string:

Custom Tab Labels

Usetitle="..."to override the default language-derived label:

:::{code-tabs}

```javascript title="React"
const [count, setCount] = useState(0);
```

```javascript title="Vue"
const count = ref(0);
```

:::

Files Without Extensions

For files likeDockerfile that have no extension, use title=:

:::{code-tabs}

```dockerfile title="Dockerfile"
FROM python:3.14-slim
```

```yaml docker-compose.yml
services:
  web:
    build: .
```

:::

Code Tabs vs Tab-Set

Feature code-tabs tab-set
Syntax Just code fences Nested:::{tab-item}
Auto sync ✅ All code-tabs sync by language Manual with:sync:
Language icons ✅ Automatic Manual with:icon:
Copy button ✅ Built-in ❌ None
Line numbers ✅ Auto for 3+ lines ❌ None
Best for Code examples Mixed content

Tip

Usecode-tabs when you're showing the same concept in multiple programming languages. Use tab-setwhen tabs contain mixed content (text, images, etc.) or aren't code-focused.

Inline Code

For inline code, use single backticks:

Run `bengal build` to generate your site.

Result: Run bengal buildto generate your site.

Code with Caption

Add a caption to your code block:

```python
:caption: Example: Hello World function

def hello():
    print("Hello, World!")
```

Diff Highlighting

Show code changes with diff syntax:

```diff
- old_function()
+ new_function()
  unchanged_line()
```

Console/Terminal Output

For terminal sessions, useconsole or shell-session:

```console
$ bengal build
Building site...
✓ Built 42 pages in 1.2s
```

Best Practices

  • Always specify a language for syntax highlighting
  • Useliteralincludefor code that must stay in sync with source
  • Highlight the important lines to guide readers
  • Keep code examples short and focused on one concept
  • Add line numbers when referencing specific lines in text

Syntax Themes

Bengal's syntax highlighting uses Rosettes, which provides configurable themes that adapt to light/dark mode.

Available Themes

Theme Description Mode
bengal-tiger Bengal brand theme with orange accents Dark
bengal-snow-lynx Light variant with warm teal Adaptive
bengal-charcoal Minimal dark variant Dark
bengal-blue Blue accent variant Dark
monokai Classic warm, vibrant theme Dark
dracula Purple accent theme Dark
github GitHub's syntax theme Adaptive
github-light GitHub light mode only Light
github-dark GitHub dark mode only Dark

Configuration

Configure syntax highlighting inconfig/_default/theme.yaml:

theme:
  # Site palette (syntax inherits from this when theme is "auto")
  default_palette: "snow-lynx"

  syntax_highlighting:
    # Theme selection:
    # - "auto": Inherit from default_palette (recommended)
    # - Specific theme name: "monokai", "dracula", etc.
    theme: "auto"

    # CSS class output style:
    # - "semantic": Human-readable classes (.syntax-function, .syntax-string)
    # - "pygments": Pygments-compatible short classes (.nf, .s)
    css_class_style: "semantic"

Palette Inheritance

Whentheme: "auto" is set, the syntax theme automatically inherits from your site's default_palette:

Site Palette Syntax Theme
default/ empty bengal-tiger
snow-lynx bengal-snow-lynx
brown-bengal bengal-tiger
silver-bengal bengal-charcoal
charcoal-bengal bengal-charcoal
blue-bengal bengal-blue

CSS Class Styles

Rosettes supports two CSS class naming conventions:

Human-readable class names that describe the code element's purpose:

<span class="syntax-function">greet</span>
<span class="syntax-string">"Hello"</span>
<span class="syntax-keyword">def</span>

Best for: New projects, custom themes, semantic CSS.

Short class names compatible with existing Pygments themes:

<span class="nf">greet</span>
<span class="s">"Hello"</span>
<span class="k">def</span>

Best for: Migrating from Pygments, using existing Pygments CSS themes.

Note

Rosettes is designed for Python 3.14t free-threading with zero global mutable state. It provides thread-safe syntax highlighting with O(n) guaranteed parsing. See Rosettes Performance for benchmarks.

Seealso

Rosettes Documentation: