Syntax Highlighting

Code blocks in Markdown are automatically syntax highlighted.

Usage

Use fenced code blocks with a language identifier:

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
```

Supported Languages

Common languages:

Language	Identifiers
JavaScript	javascript, js
TypeScript	typescript, ts
Python	python, py
Ruby	ruby, rb
Go	go, golang
Rust	rust, rs
Crystal	crystal, cr
HTML	html
CSS	css
JSON	json
YAML	yaml, yml
TOML	toml
Markdown	markdown, md
Shell	bash, sh, shell
SQL	sql

Configuration

Configure in config.toml:

[highlight]
enabled = true
theme = "github-dark"
use_cdn = true
mode = "client"

Key	Type	Default	Description
enabled	bool	true	Enable syntax highlighting
theme	string	"github"	Highlight.js theme name
use_cdn	bool	true	Load assets from CDN (false = local files)
mode	string	"client"	`"client"` highlights in the browser via Highlight.js; `"server"` highlights at build time
line_numbers	bool	false	Add line numbers to every fenced code block by default (see below)

Server-Side Highlighting

With mode = "server", code blocks are highlighted during the build — no JavaScript ships to the browser, and code is colored even with JavaScript disabled:

[highlight]
mode = "server"
theme = "github-dark"

The build-time highlighter emits Highlight.js-compatible CSS classes, so every theme above keeps working unchanged: {{ highlight_css }} still injects the theme stylesheet, while {{ highlight_js }} becomes empty.

Over 250 languages are supported (via Tartrazine lexers, ported from Pygments/Chroma). Code blocks in languages without a lexer fall back to plain, unhighlighted output.

Line Numbers and Highlighted Lines

A fenced code block's language can be followed by an options block — {...} — to add line numbers and/or highlight specific lines:

```python {linenos=true, hl_lines="2-4 7", linenostart=5}
def main():
    setup()
    run()
    teardown()
    return 0
```

Option	Value	Description
`linenos`	`true` / `false`	Show a line-number gutter. Overrides the `[highlight] line_numbers` default for this block.
`hl_lines`	e.g. `"2-4 7"`	Highlight these lines — space/comma-separated line numbers and/or ranges. Always the block's own physical 1-based lines, never shifted by `linenostart`.
`linenostart`	e.g. `5`	First displayed line number (default `1`). Only affects the numbers shown — it does not change which physical lines `hl_lines` highlights.

The block accepts a couple of equivalent forms: python {linenos=true}, python{linenos=true} (no space), or {linenos=true} alone (no language). A malformed or unrecognized options block (e.g. {oops}) is left as literal text in the language token, exactly as if fence options didn't exist.

Setting [highlight] line_numbers = true turns line numbers on for every fenced code block with a language — a per-block {linenos=false} opts back out.

Server vs client mode:

mode = "server" renders the full result at build time: each line is wrapped in its own element, so line numbers and highlighted lines appear with no JavaScript.
mode = "client" (default) does not re-render the body — instead the <pre> tag gets data-linenos="true", data-linenostart="N" (when greater than 1), and/or data-hl-lines="2-4 7" attributes, so a client-side script or custom CSS can act on them. Hwaro ships no such script for client mode; full rendering requires mode = "server".

Scaffold sites style the server-mode markup out of the box. For a non-scaffold site, or a custom theme, add:

pre code .line.hl { display: inline-block; width: 100%; background: color-mix(in srgb, var(--code-keyword) 12%, transparent); }
pre code .ln { user-select: none; -webkit-user-select: none; opacity: .45; }

(Swap var(--code-keyword) for any color that fits your theme if you aren't using the Hwaro Ember token system.)

Themes

Hwaro uses Highlight.js themes. Any valid Highlight.js theme name works. Popular choices:

github — Light GitHub style (default)
github-dark — Dark GitHub style
github-dark-dimmed — Dimmed dark GitHub style
monokai — Classic dark theme
dracula — Dark purple theme
solarized-dark — Solarized dark
solarized-light — Solarized light
nord — Arctic color palette
tokyo-night-dark — Tokyo Night dark

Browse all available themes at highlightjs.org/demo.

CDN vs Local

When use_cdn = true (default), assets are loaded from cdnjs:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>

When use_cdn = false, assets are loaded from local paths:

<link rel="stylesheet" href="/assets/css/highlight/github-dark.min.css">
<script src="/assets/js/highlight.min.js"></script>

You must provide the local files yourself when using use_cdn = false.

Template Integration

Include highlighting assets in templates:

<head>
  {{ highlight_css | safe }}
</head>
<body>
  ...
  {{ highlight_js | safe }}
</body>

Or combined:

<head>
  {{ highlight_tags | safe }}
</head>

Build Options

Disable highlighting for faster builds:

hwaro build --skip-highlighting

Plain Text Blocks

For no highlighting, omit the language or use text:

```text
Plain text content
No highlighting applied
```

Inline Code

Inline code uses backticks and is not highlighted:

Use the `console.log()` function.