module Asciidoctor::SyntaxHighlighter

Public: A pluggable adapter for integrating a syntax (aka code) highlighter into AsciiDoc processing.

There are two types of syntax highlighter adapters. The first performs syntax highlighting during the convert phase. This adapter type must define a highlight? method that returns true. The companion highlight method will then be called to handle the :specialcharacters substitution for source blocks. The second assumes syntax highlighting is performed on the client (e.g., when the HTML document is loaded). This adapter type must define a docinfo? method that returns true. The companion docinfo method will then be called to insert markup into the output document. The docinfo functionality is available to both adapter types.

Asciidoctor provides several built-in adapters, including coderay, pygments, rouge, highlight.js, html-pipeline, and prettify. Additional adapters can be registered using SyntaxHighlighter.register or by supplying a custom factory.

Attributes

name[R]

Public: Returns the String name of this syntax highlighter for referencing it in messages and option names.

Public Class Methods

new(name, backend = 'html5', opts = {}) click to toggle source

# File lib/asciidoctor/syntax_highlighter.rb, line 18
def initialize name, backend = 'html5', opts = {}
  @name = @pre_class = name
end

Public Instance Methods

docinfo(location, doc, opts) click to toggle source

Public: Generates docinfo markup for this syntax highlighter to insert at the specified location in the output document. Should be called by converter after main content has been converted.

location - The Symbol representing the location slot (:head or :footer). doc - The Document in which this syntax highlighter is being used. opts - A Hash of options that configure the syntax highlighting:

:linkcss - A Boolean indicating whether the stylesheet should be linked instead of embedded (optional).
:cdn_base_url - The String base URL for assets loaded from the CDN.
:self_closing_tag_slash - The String '/' if the converter calling this method emits self-closing tags.

Return the [String] markup to insert.

# File lib/asciidoctor/syntax_highlighter.rb, line 41
def docinfo location, doc, opts
  raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #docinfo? returns true)
end

docinfo?(location;) click to toggle source

Public: Indicates whether this syntax highlighter has docinfo (i.e., markup) to insert into the output document at the specified location. Should be called by converter after main content has been converted.

location - The Symbol representing the location slot (:head or :footer).

Returns a [Boolean] indicating whether the docinfo method should be called for this location.

# File lib/asciidoctor/syntax_highlighter.rb, line 28
def docinfo? location; end

format(node, lang, opts) click to toggle source

Public: Format the highlighted source for inclusion in an HTML document.

node - The source Block being processed. lang - The source language String for this Block (e.g., ruby). opts - A Hash of options that control syntax highlighting:

:nowrap - A Boolean that indicates whether wrapping should be disabled (optional).

Returns the highlighted source [String] wrapped in preformatted tags (e.g., pre and code)

# File lib/asciidoctor/syntax_highlighter.rb, line 80
def format node, lang, opts
  raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method)
end

highlight(node, source, lang, opts) click to toggle source

Public: Highlights the specified source when this source block is being converted.

If the source contains callout marks, the caller assumes the source remains on the same lines and no closing tags are added to the end of each line. If the source gets shifted by one or more lines, this method must return a tuple containing the highlighted source and the number of lines by which the source was shifted.

node - The source Block to syntax highlight. source - The raw source text String of this source block (after preprocessing). lang - The source language String specified on this block (e.g., ruby). opts - A Hash of options that configure the syntax highlighting:

:callouts - A Hash of callouts extracted from the source, indexed by line number (1-based) (optional).
:css_mode - The Symbol CSS mode (:class or :inline).
:highlight_lines - A 1-based Array of Integer line numbers to highlight (aka emphasize) (optional).
:number_lines - A Symbol indicating whether lines should be numbered (:table or :inline) (optional).
:start_line_number - The starting Integer (1-based) line number (optional, default: 1).
:style - The String style (aka theme) to use for colorizing the code (optional).

Returns the highlighted source String or a tuple of the highlighted source String and an Integer line offset.

# File lib/asciidoctor/syntax_highlighter.rb, line 68
def highlight node, source, lang, opts
  raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #highlight? returns true)
end

highlight?() click to toggle source

Public: Indicates whether highlighting is handled by this syntax highlighter or by the client.

Returns a [Boolean] indicating whether the highlight method should be used to handle the :specialchars substitution.

# File lib/asciidoctor/syntax_highlighter.rb, line 48
def highlight?; end

write_stylesheet(doc, to_dir) click to toggle source

Public: Writes the stylesheet to support the highlighted source(s) to disk.

doc - The Document in which this syntax highlighter is being used. to_dir - The absolute String path of the stylesheet output directory.

Returns nothing.

# File lib/asciidoctor/syntax_highlighter.rb, line 98
def write_stylesheet doc, to_dir
  raise ::NotImplementedError, %(#{SyntaxHighlighter} subclass #{self.class} must implement the ##{__method__} method since #write_stylesheet? returns true)
end

write_stylesheet?(doc;) click to toggle source

Public: Indicates whether this syntax highlighter wants to write a stylesheet to disk. Only called if both the linkcss and copycss attributes are set on the document.

doc - The Document in which this syntax highlighter is being used.

Returns a [Boolean] indicating whether the write_stylesheet method should be called.

# File lib/asciidoctor/syntax_highlighter.rb, line 90
def write_stylesheet? doc; end