Highlight Select Lines

Not to be confused with source highlighting, you can highlight (i.e., emphasize) specific lines in a source block in order to call attention to them.

Usage criteria

Line highlighting can be applied to a source block if certain criteria are met.

source-highlighter Criteria to use the highlight attribute on a source block

coderay

  • The linenums option is enabled on the block.

  • The highlight attribute is defined on the block.

Line highlighting will only emphasize the line number itself.

rouge

  • The highlight attribute is defined on the block.

  • The CSS to support line highlighting is supplied by docinfo. (Needed even if rouge-css=style).

pygments

  • The highlight attribute is defined on the block.

highlight.js

Not applicable.

Line highlighting isn’t available when using highlight.js.

highlight attribute

Line highlighting is activated on a source block if the highlight attribute is defined and at least one of the line numbers falls in this range.

Keep in mind that some syntax highlighter libraries require additional options (e.g., CodeRay and Rouge), and some don’t support line highlighting at all (e.g., highlight.js).

The highlight attribute accepts a comma or semicolon delimited list of line ranges. The numbers correspond to the line numbers of the source block. If the start attribute is not specified, line numbers of the source block start at 1.

Here are some examples:

  • 1

  • 2,4,6

  • 3..5

  • 2,7..9

A line range is represented by two numbers separated by a double period (e.g., 2..5). The range is inclusive.

CodeRay

Example 1. Highlight select lines when source-highlighter=coderay
= Document Title
:source-highlighter: coderay

[%linenums,ruby,highlight=2..5]
----
ORDERED_LIST_KEYWORDS = {
  'loweralpha' => 'a',
  'lowerroman' => 'i',
  'upperalpha' => 'A',
  'upperroman' => 'I',
}
----

When using CodeRay as the source highlighter, the linenums option is required to use line highlighting. That’s because line highlighting is only applied to the line number, which is emphasized using bold text. CodeRay does not shade the line of code itself.

Rouge

Example 2. Highlight select lines when source-highlighter=rouge
= Document Title
:source-highlighter: rouge
:docinfo: shared

[,ruby,highlight=2..5]
----
ORDERED_LIST_KEYWORDS = {
  'loweralpha' => 'a',
  'lowerroman' => 'i',
  'upperalpha' => 'A',
  'upperroman' => 'I',
}
----

When using Rouge as the source highlighter, you must supply CSS to support line highlighting. You can do so by storing the required line highlighting CSS in a docinfo file, then including it in the output document by setting the docinfo document attribute.

Example 3. Docinfo file (docinfo.html) to support line highlighting with Rouge
<style>
pre.rouge .hll {
  background-color: #ffc;
  display: block;
}
pre.rouge .hll * {
  background-color: initial;
}
</style>

Note that this supplemental CSS is needed even when rouge-css=style. The Rouge integration does not embed the CSS for highlighting lines into the style attribute of the tag for each line. Instead, it sets the hll class on the tag (e.g., <span class="hll">).

Pygments

Example 4. Highlight select lines when source-highlighter=pygments
= Document Title
:source-highlighter: pygments

[,ruby,highlight=2..5]
----
ORDERED_LIST_KEYWORDS = {
  'loweralpha' => 'a',
  'lowerroman' => 'i',
  'upperalpha' => 'A',
  'upperroman' => 'I',
}
----