Includes #

With the following syntax, you can include files into your book:

\{{#include file.go}}

(Without the \)

The path to the file has to be relative from the current source file.

romero will interpret included files as Markdown. Since the include command is usually used for inserting code snippets and examples, you will often wrap the command with ``` to display the file contents without interpreting them.

```
\{{#include file.go}}
```

Syntax Reference #

The full syntax for include directives is:

\{{#include <PATH>[:<ANCHOR_OR_LINES>] [simple] [context=N]}}

Line Range Formats #

Including portions of a file #

Often you only need a specific part of the file, e.g. relevant lines for an example:

\{{#include file.go:2}}
\{{#include file.go::10}}
\{{#include file.go:2:}}
\{{#include file.go:2:10}}

The first command only includes the second line from file file.go. The second command includes all lines up to line 10, i.e. the lines from 11 till the end of the file are omitted. The third command includes all lines from line 2, i.e. the first line is omitted. The last command includes the excerpt of file.go consisting of lines 2 to 10.

Using Anchors #

To avoid breaking the documentation when modifying included files, you can also include a specific section using anchors instead of line numbers. An anchor is a pair of matching lines, beginning with ANCHOR: name and ending with ANCHOR_END: name. Those anchors are usually placed in comments:

#include <stdio.h>int main(void) {    // ANCHOR: printf
    printf("Hello World!\n");    // ANCHOR_END: printf
}

You can then include the lines between the two anchors with:

```C
\{{#include included_file.c:printf}}
```

Which renders as:

int main(void) {    // ANCHOR: printf

    printf("Hello World!\n");

    // ANCHOR_END: printf
}

Simple Mode #

By default, includes are enhanced with line numbers, context expansion, and source links. If you want the raw file content without decoration, add simple at the end:

\{{#include file.go simple}}
\{{#include file.go:2:10 simple}}
\{{#include file.go:anchor simple}}

This is useful when including content that isn’t code (such as markdown snippets) or when you prefer the default code fence styling.

Example #

Enhanced mode (default):

int main(void) {    // ANCHOR: printf

    printf("Hello World!\n");

    // ANCHOR_END: printf
}

Simple mode:

    printf("Hello World!\n");

Context Override #

You can override the number of context lines for a specific include using context=N:

\{{#include file.go:anchor context=5}}
\{{#include file.go:anchor context=0}}

Use context=0 to disable context for a specific include, or a larger value to show more surrounding code. This overrides the global include-context-lines configuration.

Enhanced Code Includes #

When using the HTML renderer (without the simple option), code includes are automatically enhanced with the following features:

Line Numbers #

Code includes display line numbers that correspond to the actual line numbers in the original source file. This makes it easy to reference specific lines when discussing code.

The line numbers are styled to be visually distinct from the code content, and are not selectable when copying code.

Context Expansion #

When including a portion of a file (using line ranges or anchors), romero captures surrounding context lines. An eye icon button appears in the top-right corner of the code block. Clicking this button reveals the hidden context lines before and after the included section, helping readers understand the broader context of the code snippet.

The context lines are displayed with a dashed border and dimmed styling to distinguish them from the main content.

Source Link #

If you configure a source-url-template in your book.toml, a code icon button will appear that links directly to the source file in your repository. The link includes the specific line numbers for the included content.

Rust Playground Integration #

When using {{#rustdoc_include}} (instead of {{#include}}), additional features are available for Rust code:

Copy to Clipboard #

A copy button allows you to quickly copy the code content to your clipboard.

Run on Rust Playground #

A play button sends the code to the Rust Playground and displays the output directly below the code block. This is useful for demonstrating runnable examples.

// ANCHOR: hello

fn main() {    println!("Hello, World!");}

// ANCHOR_END: hello

Content-Security-Policy: connect-src 'self' https://play.rust-lang.org;

Configuration Options #

The following options can be configured in [output.html] section of your book.toml:

• source-url-template: Template for generating links to source files. Uses Go template syntax with {{ .Path }}, {{ .Start }}, and {{ .End }} placeholders.
• include-line-numbers: Whether to display line numbers (default: true)
• include-context-lines: Number of context lines to capture before and after included sections (default: 3)

Example configuration:

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

See HTML Configuration for examples with GitHub, GitLab, and SourceHut.