asciidoctor rouge

= Asciidoctor Rouge
:source-language: shell
// custom
:gem-name: asciidoctor-rouge
:gem-version: 0.4.0
:gh-name: jirutka/{gem-name}
:gh-branch: master
:codacy-id: d2ed58f5f3f949a19bab7637fe7d0bdb

ifdef::env-github[]
image:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}[Build Status, link=“https://travis-ci.org/{gh-name}”]
image:https://api.codacy.com/project/badge/Coverage/{codacy-id}[“Test Coverage”, link=“https://www.codacy.com/app/{gh-name}”]
image:https://api.codacy.com/project/badge/Grade/{codacy-id}[“Codacy Code quality”, link=“https://www.codacy.com/app/{gh-name}”]
image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link=“https://rubygems.org/gems/{gem-name}”]
image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link=“http://www.rubydoc.info/github/{gh-name}/{gh-branch}”]
endif::env-github[]

This project provides an http://asciidoctor.org/[Asciidoctor] extension for highlighting source listing blocks using http://rouge.jneen.net/[Rouge] – a pure-ruby code highlighter that is compatible with pygments.

It supports all Asciidoctor features such as http://asciidoctor.org/docs/user-manual/#callouts[callouts], highlighting of specified lines (attribute highlight), http://asciidoctor.org/docs/user-manual/#passthroughs[passthroughs] inside a code and all other substitutions.

This extension is highly customizable and modular.

NOTICE: Asciidoctor already supports for Rouge since https://github.com/asciidoctor/asciidoctor/blob/master/CHANGELOG.adoc#200-2019-03-22---mojavelinux[version 2.0.0], so this extension is not needed anymore.

== Installation

To install (or update to the latest version):

[source, subs=“+attributes”]
gem install {gem-name}

or to install the latest development version:

[source, subs=“+attributes”]
gem install {gem-name} --pre

== Usage

Assign rouge to the source-highlighter attribute in your document’s header or via command-line argument.

[source, subs=“+attributes”]
asciidoctor -r {gem-name} -a source-highlighter=rouge Example.adoc

=== Attributes

You 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) or style (inline styles).
When class is used, Rouge styles for the specified theme are included in an HTML header.
Default is class.

rouge-theme::
Sets the name of the Rouge colour theme to use.
Look into https://github.com/jneen/rouge/tree/master/lib/rouge/themes[lib/rouge/themes] in the Rouge repository for a list of available themes.
Default is github.

rouge-style::
Alternative name for the rouge-theme for compatibility with asciidoctor-pdf (see https://github.com/{gh-name}/issues/3[#3]).

== License

This project is licensed under http://opensource.org/licenses/MIT/[MIT License].
For the full text of the license, see the link:LICENSE[LICENSE] file.