# Source Code Highlight

http://asciidoc.org/source-highlight-filter.html

# 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;
    }