# Code Blocks URL: /docs/content/authoring/code-blocks/ Section: authoring -------------------------------------------------------------------------------- Code Blocks 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, lock-free highlighter designed for Python 3.14t free-threading. Rosettes supports 50+ languages: Common Systems JVM &amp; .NET Data &amp; Config Scripting Web &amp; Templates Markup &amp; Docs Functional 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 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 Use literalinclude to 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 Tip Use literalinclude to 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. Use code-tabs for 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 Code Python Copy Copy I0: With Filenames and Highlights Add filenames and line highlights directly in the code fence info string: Code Pythonclient.py Copy Copy I0: Custom Tab Labels Use title="..." 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 like Dockerfile 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 Tip Use code-tabs when you're showing the same concept in multiple programming languages. Use tab-set when 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 build to 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, use console or shell-session: ```console $ bengal build Building site... ✓ Built 42 pages in 1.2s ``` Best Practices Always specify a language for syntax highlighting Use literalinclude for 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 in config/_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 When theme: "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: Semantic (Default) Pygments 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 Note Rosettes is designed for Python 3.14t free-threading with zero global mutable state. It provides lock-free, thread-safe syntax highlighting that's 3.4× faster than Pygments in parallel builds. See Rosettes Performance for benchmarks. Info Seealso Formatting Directives Reference — Complete literalinclude options Authoring Overview — Other authoring features Theming Guide — Customize your site's appearance including syntax themes Rosettes Documentation: Supported Languages — Full list of 50+ supported languages Custom Themes — Create your own syntax themes Line Highlighting — Advanced highlighting options -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1104 - Reading Time: 6 minutes