Pygments

The Pygments syntax highlighter can be used for xhtml11, html5 and bootstrap outputs (set the source-highlighter attribute to pygments).

Until now, AsciiDoc allow only to use Pygments with a default theme that look like to emacs theme. We have no way to customize this at document build time, unless editing contents of ./stylesheets/pygments.css file.

AsciiDoc-Bootstrap backend introduce in version 3.1.0 the new attribute pygments-style to change Pygments stylesheet at document build time.

Credit to AsciiDoctor GH-637 issue.

By default, AsciiDoc-Bootstrap used the AsciiDoc pygments theme. To change the style, set the pygments-style attribute and assign it the alternate style’s name.

To see what pygments styles you have available, open a terminal and type:

$ pygmentize -L styles

It will output the style names and brief descriptions.

Pygments 1.5 provides 19 themes, but only 3 pre-defined stylesheets are available in standard AsciiDoc-Bootstrap backend distribution (default, pastie, monokai).

Here are how to setup other themes. Open a terminal and type:

$ pygmentize -f html -S <theme> -a .highlight

where <theme> is one of those listed by Pygments (-L style). Copy output to the AsciiDoc-Bootstrap install dir stylesheets folder in a file named pygments.<theme>.css. (e.g. pygments.tango.css)

In the example document below, we used the monokai style as main theme, and pastie as local theme to highlight a block of CSS code.

Pygments token <span> tags will not use CSS classes, but inline styles. This is not recommended for larger pieces of code since it increases output size by quite a bit.
The source-highlighter args attribute allows the inclusion of arbitrary (highlighter dependent) command options.
== Alternate Pygments Theme
:source-highlighter: pygments
:pygments-style: monokai

[source,php,numbered]
.Using global theme [label label-default]#{pygments-style}#
----
<?php
use Symfony\Component\Finder\Finder;

$finder = new Finder();
$finder->files()->in(__DIR__);

foreach ($finder as $file) {
    // affiche le chemin absolu
    print $file->getRealpath()."\n";
    // affiche le chemin relatif d'un fichier, sans le nom du fichier
    print $file->getRelativePath()."\n";
    // affiche le chemin relatif du fichier
    print $file->getRelativePathname()."\n";
}
----


:local-css-style: pastie
[args="-O style={local-css-style},noclasses=True"]


[source,css]
.Using local theme [label label-default]#{local-css-style}#
----
/*
|--------------------------------------------------------------------------
| UItoTop jQuery Plugin 1.2
| http://www.mattvarone.com/web-design/uitotop-jquery-plugin/
|--------------------------------------------------------------------------
*/

#toTop {
        display:none;
        text-decoration:none;
        position:fixed;
        bottom:10px;
        right:10px;
        overflow:hidden;
        width:51px;
        height:51px;
        border:none;
        text-indent:100%;
        background:url(../images/icons/ui.totop.png) no-repeat left top;
}

#toTopHover {
        background:url(../images/icons/ui.totop.png) no-repeat left -51px;
        width:51px;
        height:51px;
        display:block;
        overflow:hidden;
        float:left;
        opacity: 0;
        -moz-opacity: 0;
        filter:alpha(opacity=0);
}

#toTop:active, #toTop:focus {
        outline:none;
}
----

Renders

Alternate Pygments Theme

Using global theme monokai
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?php
use Symfony\Component\Finder\Finder;

$finder = new Finder();
$finder->files()->in(__DIR__);

foreach ($finder as $file) {
    // affiche le chemin absolu
    print $file->getRealpath()."\n";
    // affiche le chemin relatif d'un fichier, sans le nom du fichier
    print $file->getRelativePath()."\n";
    // affiche le chemin relatif du fichier
    print $file->getRelativePathname()."\n";
}
Using local theme pastie
/*
|--------------------------------------------------------------------------
| UItoTop jQuery Plugin 1.2
| http://www.mattvarone.com/web-design/uitotop-jquery-plugin/
|--------------------------------------------------------------------------
*/

#toTop {
        display:none;
        text-decoration:none;
        position:fixed;
        bottom:10px;
        right:10px;
        overflow:hidden;
        width:51px;
        height:51px;
        border:none;
        text-indent:100%;
        background:url(../images/icons/ui.totop.png) no-repeat left top;
}

#toTopHover {
        background:url(../images/icons/ui.totop.png) no-repeat left -51px;
        width:51px;
        height:51px;
        display:block;
        overflow:hidden;
        float:left;
        opacity: 0;
        -moz-opacity: 0;
        filter:alpha(opacity=0);
}

#toTop:active, #toTop:focus {
        outline:none;
}