Documentation Guides

Configuration #

[output.html]
additional-js = ["custom.js"]
additional-css = ["custom.css", "custom2.css"]
git-repository-url = "https://git.sr.ht/~ne02ptzero/romero"
git-repository-icon = "fa-square-git"
edit-url-template = "http://github.com/user/repo/edit/{{ . }}"
source-url-template = "https://git.sr.ht/~user/repo/tree/main/item/src/{{ .Path }}#L{{ .Start }}-{{ .End }}"
theme = "default"
site-url = "/"
cname = ""
input-404 = ""
logo = "logo.svg"
favicon = "img/favicon.svg"
smart-punctuation = true
mathjax-support = true
d2-support = true
highlight-type = "chroma"
highlight-theme = "github-dark"
include-line-numbers = true
include-context-lines = 3

[output.html.redirect]
"/old/path.html" = "/new/path.html"

additional-js #

If you need to change or add some behavior to the rendered website, you can specify a set of Javascript files that will be loaded alongside the default ones.

additional-css #

If you need to change the appearance of the rendered website without overwriting the whole style, you can specify a set of stylesheets that will be loaded after the default ones.

git-repository-url #

A URL to the git repository of the documentation. If provided, an icon link to said repository will be rendered in the documentation.

git-repository-icon #

The Font-Awesome icon to be used for the git repository links. Defaults to the generic fa-square-git which looks like . This icon will implicitely use the fa-brands icon family. Other sensible choices could be fa-github () or fa-gitlab ()

edit-url-template #

Template to render edition / view link of specific documentation pages: a possible value could be http://github.com/user/repo/edit/{{ . }}. Use {{ . }} as the template replacer, which will render the current path of the source documentation page.

theme #

Theme to use for the rendered website. Defaults to default. Built-in themes:

See Themes for screenshots of each theme.

You can also provide your own theme by bootstrapping with romero init --templates and placing a CSS file named your-theme.css in the templates/html/css directory. You can then use your-theme in the configuration. The theme can also be overridden at build time with the --theme CLI flag on build and serve commands.

site-url #

The URL where the documentation will be hosted. Used by romero to generate absolute links on the website. This is required to ensure navigation links and script/css imports in the 404 file work correctly, even when accessing urls in subdirectories. Defaults to /.

cname #

The DNS subdomain or apex domain at which your book will be hosted. This string will be written to a file named CNAME in the root of your site, as required by GitHub Pages.

input-404 #

The name of the markdown file used for missing files. The corresponding output file will be the same, with the extension replaced with html. Defaults to empty, which uses an embedded 404.md.

Path of an image file that will be used as the logo for the rendered website. Path must be either absolute or relative to the configuration file.

favicon #

Path or URL of an image file that will be used as the favicon for the rendered website. If a URL starting with http is provided, it will be used directly. Otherwise, the path is resolved relative to the source directory and the file is copied to the build output.

smart-punctuation #

Converts quotes to curly quotes, … to …, – to en-dash, and — to em-dash. See Smart Punctuation. Defaults to true.

mathjax-support #

Adds support for MathJax. Defaults to true.

d2-support #

Adds support for D2 diagrams. Defaults to true.

highlight-type #

Type of code-highlight engine to use. Can be either:

highlight-theme #

Theme to use when rendering code. Defaults to github-dark.

For chroma, see available themes at: https://swapoff.org/chroma/playground/

For highlightjs, the following themes are bundled and work offline:

See all highlight.js themes at: https://highlightjs.org/demo

source-url-template #

Template for generating links to source files in code includes. When configured, a code icon button appears on included code blocks that links directly to the source file in your repository.

Uses Go template syntax with the following placeholders:

Examples for different git forges:

GitHub:

[output.html]
source-url-template = "https://github.com/user/repo/blob/main/src/{{ .Path }}#L{{ .Start }}-L{{ .End }}"

GitLab:

[output.html]
source-url-template = "https://gitlab.com/user/repo/-/blob/main/src/{{ .Path }}#L{{ .Start }}-{{ .End }}"

SourceHut:

[output.html]
source-url-template = "https://git.sr.ht/~user/repo/tree/main/item/src/{{ .Path }}#L{{ .Start }}-{{ .End }}"

include-line-numbers #

Whether to display line numbers in code includes. Line numbers correspond to the actual line numbers in the original source file. Defaults to true.

[output.html]
include-line-numbers = true

include-context-lines #

Number of context lines to capture before and after included code sections (when using line ranges or anchors). These context lines are hidden by default but can be revealed by clicking the eye icon button. Defaults to 3. Set to 0 to disable context capture.

[output.html]
include-context-lines = 3

[output.html.redirect] #

A map of source paths to target paths used to create redirects in the built output. Each entry creates a symbolic link from the source to the target inside the build directory. This is useful when renaming or moving pages, so that old URLs continue to work.

[output.html.redirect]
"/old/page.html" = "/new/page.html"
"/legacy/guide.html" = "/updated/guide.html"

Source paths have their leading / stripped before creating the symlink. Parent directories are created automatically.