This project provides an Asciidoctor extension for highlighting source listing blocks using Rouge – a pure-ruby code highlighter that is compatible with pygments.
It supports all Asciidoctor features such as callouts, highlighting of specified lines (attribute highlight), passthroughs inside a code and all other substitutions.
This extension is highly customizable and modular.
To install (or update to the latest version):
gem install asciidoctor-rougeor to install the latest development version:
gem install asciidoctor-rouge --preAssign rouge to the source-highlighter attribute in your document’s header or via command-line argument.
asciidoctor -r asciidoctor-rouge -a source-highlighter=rouge Example.adocYou can further customize the source block output with additional Rouge attributes:
- rouge-css
-
Controls what method is used for applying CSS to the tokens. Can be
class(CSS classes),style(inline styles) orexternal(external styles). Whenclassis used, Rouge styles for the specified theme are included in an HTML header. Whenexternalis specified, CSS classes are used but no styles will be added except whenrouge-themeis not empty in which case its value is interpreted as a URL to a style sheet and a link to that style sheet will be added to the HTML header. Default isclass. - rouge-theme
-
Sets the name of the Rouge colour theme to use. Look into lib/rouge/themes in the Rouge repository for a list of available themes. Default is
github. - rouge-style
-
Alternative name for the
rouge-themefor compatibility with asciidoctor-pdf (see #3). - rouge-highlighted-class
-
CSS class to use on a line wrapper element for highlighted lines. Default is
highlighted. - rouge-line-class
-
CSS class to set on a line wrapper element Default is
line. - rouge-line-id
-
Format string for specifying an HTML
idfor each line (e.g. withrouge-line-id="L%i"each line of the listing will get an id of the formid="L1",id="L2", etc.). This really only makes sense if the format string is distinct for each source listing, otherwise it will lead to duplicate IDs which makes the generated HTML invalid. Default is no line ids.
Rouge allows passing certain options to its Lexer classes when selecting the language to parse. This feature is also available from within Asciidoctor. So instead of simply writing:
[source, console]to select console as output language (with its default options) you can also write:
[source, "console?prompt=$> "]This will also select console as output language but it will additionally set the prompt string to $> . Options are comma separeted key=value pairs which are appended to the language string with a ?-character. Consult the various Rouge Lexer classes to find out which additional options they support.
This project is licensed under MIT License. For the full text of the license, see the LICENSE file.