NAME

Statocles::Plugin::Highlight::Kamelon - Highlight code

VERSION

version 1.000

SYNOPSIS

  # Configuration in site.yml
  site:
    class: Statocles::Site
    plugins:
      highlight:
        $class: Statocles::Plugin::Highlight::Kamelon
        $args:
          style: default

  # Usage in Markdown files
  %= highlight Perl => begin
  print "hello, world\n"
  %end

  %= highlight Perl => include -raw => 'hello.pl'

DESCRIPTION

A plugin for the static website generator Statocles that adds an alternative syntax highlighter. Source code and configuration examples in Markdown files are highlighted with Syntax::Kamelon.

ATTRIBUTES

style

The plugin uses Cascading Style Sheets that are provided by Statocles::Plugin::Highlight.

• default

• solarized-dark

• solarized-light

Download additional style sheets from the Highlight.js project and put the files into your theme's plugin/highlight directory.

SUBROUTINES/METHODS

highlight

  %= highlight Bash => begin
  echo "hello, world"
  %end

  %= highlight 'Intel x86 (NASM)' => include -raw => 'hello.nasm'

  %= highlight -style => 'solarized-dark', Kotlin => begin
  println("hello, world")
  %end

Highlights code with the specified syntax. Enclose code in begin...end blocks or include code from files. See "BUGS AND LIMITATIONS" for caveats. Use a different style sheet by passing a -style option.

Run the following command to output the languages and file formats that are supported by Syntax::Kamelon:

  perl -MSyntax::Kamelon -E \
  'say for sort { fc $a cmp fc $b } Syntax::Kamelon->new->AvailableSyntaxes'

register

  $plugin->register($site);

Registers the "highlight" helper function. Automatically called by Statocles if the plugin is added to the site.yml.

DIAGNOSTICS

Don't know how to highlight "SYNTAX"

The specified syntax is unknown.

CONFIGURATION AND ENVIRONMENT

Register the plugin in your site.yml.

  site:
    class: Statocles::Site
    plugins:
      highlight:
        $class: Statocles::Plugin::Highlight::Kamelon
        $args:
          style: default

DEPENDENCIES

Requires Perl 5.16 and the modules Statocles and Syntax::Kamelon from CPAN.

INCOMPATIBILITIES

This plugin provides a "highlight" helper function and thus conflicts with Statocles::Plugin::Highlight. A Statocles site cannot register both plugins.

BUGS AND LIMITATIONS

Do not highlight code from untrusted sources in begin...end blocks. Statocles interprets Mojo::Template tags in such blocks. Escape tags in the source code with %. For example, replace <% with <%%.

Always include files with -raw, which disables the template tags.

See Syntax::Kamelon for the syntax highlighter's limitations.

AUTHOR

Andreas Vögele <voegelas@cpan.org>

LICENSE AND COPYRIGHT

Copyright (C) 2023 Andreas Vögele

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Statocles::Plugin::Highlight::Kamelon

perl -MCPAN -e shell
install Statocles::Plugin::Highlight::Kamelon