view release on metacpan or  search on metacpan

lib/Daizu/Plugin/SyntaxHighlight.pm  view on Meta::CPAN

package Daizu::Plugin::SyntaxHighlight;
use warnings;
use strict;

use Text::VimColor;
use Daizu;

=head1 NAME

Daizu::Plugin::SyntaxHighlight - a plugin for syntax-highlighting code samples in HTML pages

=head1 DESCRIPTION

This plugin filters XHTML content expanding any
C<daizu::syntax-highlight> elements by passing their contents through
the L<Text::VimColor> module, which is required for it to work.  The source
of your articles can contain markup like this:

=for syntax-highlight xml

    <daizu:syntax-highlight filetype="perl">
    # A piece of Perl code which will be syntax highlighted.
    my $foo = 'bar';
    </daizu:syntax-highlight>

The C<daizu> prefix should be bound to the
L<Daizu HTML extension namespace|Daizu/$Daizu::HTML_EXTENSION_NS>
(which is done automatically for the content of XHTML articles).  The output
will be an HTML C<pre> element, containing text and C<span> elements with
appropriate classes.

Extra whitespace at the start or end of the content is trimmed off.

If you want to highlight a larger amount of code, put it in a separate
file and use XInclude to insert it into the C<syntax-highlight> element.
For example:

=for syntax-highlight xml

    <daizu:syntax-highlight filetype="sql">
    <xi:include href="database-schema.sql" parse="text"/>
    </daizu:syntax-highlight>

Note that the C<xi:include> element isn't indented, because that might
leave an extra bit of indentation on the first line.

You can also use a different element instead of C<pre>.  For example
to highlight a Perl regular expression which appears in a paragraph,
you can instead use a C<code> element:

=for syntax-highlight xml

    <daizu:syntax-highlight filetype="perl" element="code"
      >/^_index\./</daizu:syntax-highlight>

=head1 CONFIGURATION

To turn on this plugin, include the following in your Daizu CMS configuration
file:

=for syntax-highlight xml

    <plugin class="Daizu::Plugin::SyntaxHighlight" />

All files which have a C<daizu:type> property of 'article' will then
be filtered by this module.

=head1 STYLING

For the highlighting to be presented properly you will have to provide some
rules in your CSS stylesheet.  The following works well if your C<pre> blocks
will have a white background:

=for syntax-highlight css

    span.syn-comment    { color: #0000FF }
    span.syn-constant   { color: #FF00FF }
    span.syn-identifier { color: #008B8B }
    span.syn-statement  { color: #A52A2A ; font-weight: bold }
    span.syn-preproc    { color: #A020F0 }
    span.syn-type       { color: #2E8B57 ; font-weight: bold }
    span.syn-special    { color: #6A5ACD }
    span.syn-underlined { color: #000000 ; text-decoration: underline }
    span.syn-error      { color: #FFFFFF ; background: #FF0000 none }
    span.syn-todo       { color: #0000FF ; background: #FFFF00 none }

The Daizu CMS default stylesheet has these rules included already.