File and Line Number Information

The sourcemap is an AsciiDoc processor feature that tracks and stores the file and line number for each parsed AsciiDoc block. Some Asciidoctor extensions rely on this information to run successfully or return the correct output. Antora’s logger uses this information to add line number and include directive source file location context to the error, warning, and info messages it logs that concern the AsciiDoc syntax. For example, when the AsciiDoc processor’s sourcemap is turned on (activated), Antora’s logger can provide the line number where an unresolved xref is located in a file. If the sourcemap is turned off, the logger can only provide the location of the page file that contains the broken xref.

The sourcemap feature is turned on by activating the sourcemap key in your playbook or using the --asciidoc-sourcemap option.

The sourcemap key is set to false by default. That is, it’s deactivated (turned off) at runtime unless activated in the playbook or from the CLI using the --asciidoc-sourcemap option.

The optional sourcemap key is mapped to the asciidoc key.

To activate the sourcemap key, assign it the value true in the playbook file.

You don’t have to modify the playbook file directly to activate or deactivate this key. To activate the sourcemap from the CLI, use the --asciidoc-sourcemap option.

The --asciidoc-sourcemap option overrides a value assigned to the sourcemap key in the playbook file.

When the sourcemap key is activated in a playbook file, it cannot be deactivated from the command line. The CLI can only activate it.