Add dedicated section or page for the linenums option on source blocks
Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/77
Source blocks support the linenums
option. This option adds line numbers to the rendered source block when supported by the source highlighter or converter.
:source-highlighter: rouge
[source%linenums,js]
----
function fib (n) {
if (n < 2) return n
return fib(n - 1) + fib(n - 2)
}
console.log([1, 2, 3, 4, 5].map(fib))
----
The linenums
option can also be specified as the third positional (unnamed) attribute on the source block.
:source-highlighter: rouge
[source,js,linenums]
----
function fib (n) {
if (n < 2) return n
return fib(n - 1) + fib(n - 2)
}
console.log([1, 2, 3, 4, 5].map(fib))
----
However, the named option is preferred. The option can also be enabled globally by setting the source-linenums-option
attribute.
The docs should emphasize that while the option is a part of the AsciiDoc language, it does require support from the toolchain (syntax highlighter adapter, converter, and/or output format), so it may not always be honored.
The linenums
option is documented in passing in the Asciidoctor docs on the page for each syntax highlighter adapter. See:
- https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/pygments/
- https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/rouge/
- https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/coderay/
However, this topic deserves its own section or page to define it and solidify it as part of the AsciiDoc language.