Configuration #
The html-single renderer reads configuration from [output.html-single] in your book.toml. If this section is not present, it falls back to [output.html] settings.
[output.html-single]
toc-depth = 3
number-sections = true
highlight-type = "chroma"
highlight-theme = "github-dark"
mathjax-support = true
d2-support = true
smart-punctuation = true
favicon = "img/favicon.svg"
source-url-template = "https://github.com/user/repo/blob/main/src/{{ .Path }}#L{{ .Start }}-L{{ .End }}"
include-line-numbers = true
include-context-lines = 3
toc-depth #
Maximum depth for the table of contents. Entries deeper than this level will not appear in the TOC. Defaults to 3.
[output.html-single]
toc-depth = 2
number-sections #
Whether to number chapters and sections (e.g., “1”, “2”, “5.1”, “5.2”). When enabled, section numbers are clickable anchor links. Defaults to true.
[output.html-single]
number-sections = true
highlight-type #
Syntax highlighting engine to use. Defaults to chroma.
chroma— Server-side highlighting using Chroma. Code is highlighted at build time.none— No syntax highlighting.
[output.html-single]
highlight-type = "chroma"
highlight-theme #
Color theme for syntax highlighting. Only applies when using chroma. Defaults to github-dark.
See available themes at: https://swapoff.org/chroma/playground/
[output.html-single]
highlight-theme = "monokai"
mathjax-support #
Enable KaTeX math rendering for LaTeX equations. When enabled, the KaTeX CSS is loaded from CDN. Defaults to false.
[output.html-single]
mathjax-support = true
With this enabled, you can use inline math with $...$ and display math with $$...$$:
The area of a circle is $A = \pi r^2$.
$$
E = mc^2
$$
d2-support #
Enable D2 diagram rendering. Defaults to true.
[output.html-single]
d2-support = true
favicon #
Path or URL of an image file to use as the favicon. If a URL starting with http is provided, it will be used directly. Otherwise, the file is read from the source directory and embedded as a base64 data URI.
[output.html-single]
favicon = "img/favicon.svg"
smart-punctuation #
Automatically converts ASCII punctuation to typographic equivalents. Defaults to true.
- Straight quotes → curly quotes ("…" and ‘…’)
...→ ellipsis (…)--→ en-dash (–)---→ em-dash (—)
[output.html-single]
smart-punctuation = true
Code Include Options #
These options control how {{#include}} and {{#rustdoc_include}} directives render code snippets.
source-url-template #
Template for generating “View source” links on code includes. Uses Go template syntax with {{ .Path }}, {{ .Start }}, and {{ .End }} placeholders. No default.
[output.html-single]
source-url-template = "https://github.com/user/repo/blob/main/src/{{ .Path }}#L{{ .Start }}-L{{ .End }}"
include-line-numbers #
Whether to display line numbers in code includes. Defaults to true.
[output.html-single]
include-line-numbers = true
include-context-lines #
Number of context lines to show before and after included code snippets. These lines are hidden by default but can be revealed by clicking the eye icon. Defaults to 3.
[output.html-single]
include-context-lines = 5
Set to 0 to disable context lines entirely.
Configuration Fallback #
If [output.html-single] is not defined, the renderer will use settings from [output.html]. This allows you to share configuration between renderers:
[output.html]
mathjax-support = true
highlight-theme = "github-dark"
# html-single will inherit the above settings
# You can override specific options:
[output.html-single]
number-sections = false