File and Line Number Information
sourcemap key, when activated, provides additional file and line number information about AsciiDoc blocks to Antora’s logger and Asciidoctor extensions.
What is the sourcemap?
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.
Default sourcemap value
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.
sourcemap key is mapped to the asciidoc key.
asciidoc: sourcemap: true
To activate the
sourcemap key, assign it the value
true in the playbook file.
AsciiDoc sourcemap option
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.
$ antora --asciidoc-sourcemap antora-playbook.yml
--asciidoc-sourcemap option overrides a value assigned to the
sourcemap key in the playbook file.
sourcemap key is activated in a playbook file, it cannot be deactivated from the command line.
The CLI can only activate it.