WP-GeSHi-Highlight

WP-GeSHi-Highlight

A WordPress plugin by Jan-Philip Gehrcke, featuring:

  • Syntax highlighting for 240 languages (based on GeSHi).
  • Stability, performance and security inherited from GeSHi.
  • Line numbering (optional). Code-number displacements never occur. Numbers are not copied in most browsers.
  • Simple usage.
  • If desired, styles are highly & easily configurable.
  • Per-block styles: each code block on a single web page can be designed on its own.
  • High performance.
  • Clean, small and valid HTML output.
  • Clean and well-documented source code.

Contact:

jgehrcke@googlemail.com or please leave a comment below.

What do you want to do now?

Examples

What follows is a snippet of source code, displayed by WP-GeSHi-Highlight in the default style of my website.

  1. function wp_geshi_filter_and_replace_code_snippets() {
  2.     global $wp_query;
  3.     // Iterate over all posts in this query.
  4.     foreach ($wp_query->posts as $post) {
  5.         // Extract code snippets from the content. Replace them.
  6.         $post->post_content = wp_geshi_filter_replace_code($post->post_content);
  7.         if (is_single()) {
  8.             $comments_array = get_approved_comments($post->ID);
  9.             // Iterate over all approved comments belonging to this post.
  10.             // Filter them, too.
  11.             foreach ($comments_array as $comment) {
  12.                 $comment->comment_content = wp_geshi_filter_replace_code(
  13.                     $comment->comment_content);
  14.                 }
  15.             }
  16.         }
  17.     }

The corresponding pre block is configured with the arguments lang="php" and line="1". The exterior block style (the borders, the shadows, etc.) is defined in the wp-geshi-highlight.css file located in my WordPress theme’s directory.

Let us have a look at a different example. This time, the code block is configured with lang="bash" and we use a different block style, via the cssfile="another_style" argument:

$ dd if=/dev/zero of=image.ext3 bs=1M count=10000 oflag=append conv=notrunc

In this example, the WP-GeSHi-Highlight looks for another_style.css on the server and finds it. What follows is the content of another_style.css, using pure GeSHi styling, activated via lang="css" and cssfile="none" options:

.another_style {
  font-size: 12px;
  line-height: 13px;
  background-color: #EFEFF7;
  border-top: 1px solid silver;
  border-bottom: 1px solid silver;
  padding-left: 5px;
  }

What you see above is the default pre-style of my WordPress theme combined with the styling as produced by GeSHi.

General usage

Write your post or page in the raw HTML editor. The general syntax for highlighting your code using this plugin is

<pre arguments>
 
[... CODE ...]
 
</pre>

The required argument is:

  • lang="languagestring": allowed values are listed here.

Optional arguments are:

  • line="1": enables line numbering. Select the start number? See FAQ.
  • cssfile="string": selects a CSS file to style this code block.
    Allowed values:

    • "none": all block styling is omitted. The code is still highlighted by GeSHi.
    • "filename": If the file filename.css exists in the plugin directory or in WordPress’ stylesheet_directory (takes precedence), it is used to style the code block. Hence, if you store another_style.css on your server, you can use it by setting cssfile="another_style".

    If you do not set this at all, wp-geshi-highlight.css styles your code block.

  • escaped="true": the code is run through PHP’s htmlspecialchars_decode().

How to apply your own styles

Permanently change the default style:
By default, wp-geshi-highlight.css from the plugin directory is inserted into the HTML head and defines the default code block style (in combination with your theme’s CSS code). You can permanently change the default code block style by placing your own wp-geshi-highlight.css in WordPress’ stylesheet_directory (which usually is the theme style directory). If WP-GeSHi-Highlight finds it there, it takes precedence and is inserted into the HTML head instead of the default file. Obviously, such custom styling survives WP-GeSHi-Highlight updates.

Apply different styles to different code blocks:
Provide your own CSS file and use the cssfile option. Consider, for example, cssfile="another_style". This will make two things happen:

  • WP-GeSHi-Highlight puts the following structure around the HTML code generated by GeSHi:

    <div class="another_style-wrap5">
        <div class="another_style-wrap4">
            <div class="another_style-wrap3">
                <div class="another_style-wrap2">
                    <div class="another_style-wrap">
                        <div class="another_style">
                            HTML code generated by GeSHi
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </div>

    As you can see, the names of the six CSS classes depend on the value given to cssfile.

  • WP-GeSHi-Highlight looks for another_style.css in WP-GeSHi-Highlight’s plugin directory as well as in WordPress’ stylesheet_directory. If it is found, it is included in the HTML header of your website (whereas the style sheet directory takes precedence over the plugin directory).

Hence, you have plenty of room to style your code block within another_style.css, using the six different CSS classes.

FAQ

Can I change the starting line number?
Yes, try e.g. line="13". But this breaks XHTML strict compliance.

How can I use the pre and other HTML tags in my code?
Make use of HTML escape sequences and the escaped option. Write the code like that:

&lt;pre lang="html4strict" escaped="true"&gt;
hello!
&lt;/pre&gt;

It will end up like:

<pre lang="html4strict" escaped="true">
hello!
</pre>

Note that the only difference between both code blocks is that in the upper one I did not use escaped="true" in order to demonstrate what you actually have to type.

13 Pingbacks/Trackbacks