GeSHi Code Highlighter - erikswan.net

Welcome to the documentation for my GeSHi Code Highlighter script. I'll hopefully try to cover all questions, scenarios, features, and possible problems here, but if you find a bug, have a problem, or have a question, feel free to send me a note using the contact form and I'll try to get back to you ASAP. :)

Installation

First, if you don't already have a copy of the script, download it here.

System requirements:

PHP (4.4.x or above). 5.x.x is preferred because it's the only version that the script's been tested on, but I see no reason it wouldn't work on PHP 4 (the 4.4.x is due to the system requirements of GeSHi)
GeSHi (1.0.8.4 or above — let me know if a newer version breaks something)
Approx. 5MB of space.

Assuming that you've downloaded the script and your system meets the requirements, extract it and then upload it to your chosen directory. If you plan on using the script for more than one page, I recommend creating a new directory that will hold only the script includes.

Next, copy example.php to the directory of the content to be highlighted and rename it, and then open it in your favorite text editor.

Parameters

Now let me explain the different parameters that are available to you in the main file.

$input_file - This is the name of the input file that will be highlighted. Default: example_input.html

$generated_file - This is the file that will be produced when the script highlights the input file. It will not be visible to the end user, so the name doesn't really matter. Just make sure that the filename that you give doesn't already exist on your server, otherwise that file will be overwritten. Default: example_generated.html

$geshi_path - The path to GeSH. If GeSHi (geshi.php) is installed in the same directory as this file, leave this blank. Otherwise, make sure to include a trailing slash. Default: GeSHi-1.0.8.4/

$strip_slashes - If you see escaped characters in the output (things like \" \' etc.) change this to true, and slashes will be stripped before processing. This shouldn't be happening, but this value is here for backup. Default: false

$write_comment - When this is true the script will write an HTML comment at the end of the page that will let you know whether a new file is generated or not. Ex: . Default: true

In addition, below the configuration parameters there is this line:
require_once "highlight.php";
If you are planning to use the script on more than one page and/or highlight.php is in a different directory than the configuration file, make sure you change this path to reflect that!

Input formatting

First of all, make sure you include geshi.css or your own CSS file in the input page using a line like this in the head of your page (between <head> and </head>):
<link href="geshi.css" rel="stylesheet" type="text/css" />
This will ensure that the code is styled correctly.

In order for the script to highlight code, you must format blocks of code in your input file like this:

<pre lang="cpp" lines="2,6">
#include 
using namespace std;

int main ()
{
  cout << "Hello World!";
  return 0;
}
</pre>

There are two parameters here, and the second one is optional. Put the language of the code block in the lang attribute. For supported languages, visit the GeSHi website, and for their proper language codes, look in the geshi directory of your GeSHi installation (the names of the language files).

The lines attribute can be used to designate any number of lines for "extra" highlighting to draw attention to them. Note that the lines attribute is optional but if you are going to use it, it must come directly after the lang attribute because of the way the code is parsed. Line numbers should be seperated using commas without any spaces.

You can have as many code blocks on a page as you wish, and they do not have to be the same language. :)

That's it!

If you've followed the steps above, you should now be able to visit the main PHP file (formerly named example.php) and see your input content highlighted and ready to go!

If you're having problems, see the troubleshooting section.

Advanced customization

Changing the CSS styling
If you want to change the colors, borders, fonts, etc. that are applied to the code you can do so by editing the geshi.css file. Each language has it's own block of CSS styling, so you could style differently for each language if you wanted to. Note that if you want to change more advanced or structural things like the code container, line numbers, headers, footers, etc. you will have to edit the GeSHi parameters (see below).

Changing GeSHi parameters
If you want to change GeSHi parameters (things like the code container, headers and footers, line numbers, etc.) , take a look at line 54 in highlight.php. This is where you can specify additional parameters or change the default ones. Note that any changes you make here will be applied to every code block on every file that references that copy of highlight.php. For your reference, the GeSHi documentation is here.

Using parts of the script for a plugin/CMS/forum/blog/etc.
You're pretty much on your own for this one, but this is the code that searches for, collects, and then highlights code in a given string (which in my case is derived from a file).

function stylize($matches)
{    $matches[4] = preg_replace("/^[\s]+|[\s]+$/", "", $matches[4]); 
    $geshi = new GeSHi($matches[4], $matches[1]);     $geshi->enable_classes(); 
     $geshi->set_header_type(GESHI_HEADER_PRE_TABLE);
    $geshi->enable_line_numbers(GESHI_FANCY_LINE_NUMBERS, 2);    $highlightlines = explode(",", $matches[3]);
    $highlightlines = array_map(create_function('$value', 'return (int)$value;'),$highlightlines);    $geshi->highlight_lines_extra($highlightlines);
    return '<div class="mycode">'.$geshi->parse_code().'</div>';}
        $stylized_text = preg_replace_callback('/<pre\b[^>]*lang="(.+?)"\s*(lines="([0-9,]*?)")?[^>]*>(.+?)<\/pre>/s', 'stylize', $input_new_text);

You could theoretically run this on the content of a post every time the page loads and then display the highlighted version. This would be inefficient, however. It would probably be better to highlight it whenever a post is saved or edited, and then somehow store both the "highlighted" version and "non-highlighted" version - the "non-highlighted" version would be there to allow future editing. However, like I said, you're on your own if you're going to attempt this. :)

Troubleshooting

First of all, are you getting any PHP errors? If you are, this means that you likely have a syntax error, invalid value, or something is just wrong in the main config file. Read the error, go back to the file and double check all of the values.

Q: The HTML is generated and I can see the line numbers, but the code is not highlighted or styled correctly. What do I do?
A: I'm guessing that you didn't link to geshi.css in your input file (see here). If you do have it linked correctly and the code is still not styled, make sure CSS classes for the language you are using exist in geshi.css. If they don't, try either generating a new CSS file using cssgen2.php under <GeSHi directory>\contrib\ (note: the styles will be different than what is included with this script) or simply copy another language's classes and rename them to fit the language you are using.

The rest of this documentation is a work in progress, to be finished shortly.

Back to main page