Documentation

because software is just as good as it's documentation

Installation

setting up GeSHify

To install GeSHify, first extract the archive.

Then go to http://sourceforge.net/projects/geshi/files and get the latest versions of GeSHi 1.0 and GeSHi 1.1 (in the geshi-dev folder at the very bottom of the page).

Extract both archives and copy

  • from GeSHi 1.0: geshi.php and the geshi folder into system/extensions/geshi-1.0 (creating it, if it doesn't exist)
  • from GeSHi 1.1: class.geshi.php and the geshi folder into system/extensions/geshi-1.1 (also creating it, if it doesn't exist).

Now upload the contents of the system/ directory to your ExpressionEngine installation's system/ directory (which might just not be named “system”, if you renamed it).

After uploading, log in to ExpressionEngine's control panel, go to the extension manager at Admin » Utilities » Extension Manager, locate the GeSHify row in the table and click the “Enable?”-Link at the end of the line. After enabling you might want to have a look at the available settings.

Updating

Updating GeSHify is just a matter of overwriting GeSHify’s source files. GeSHify will automatically notice it’s been updated the next time it’s being used and take the necessary steps.

While you’re at updating GeSHify, you might want to update GeSHi, too.

Settings

adjusting your defaults

To adjust GeSHify's settings, log in to your control panel and open the extension manager. Locate the GeSHify row and click settings to open GeSHify's settings panel. The following settings are available:

  • cache directory
    Path to a directory where GeSHify can put it's cache files. Relative to the location of your ext.geshify.php file. Cache folder must be writable by PHP.

  • cache time
    Maximum cache time in seconds. GeSHify automatically notices if you changed code or settings since the last call, so you should not need to lower this to get current results. However, this timeout keeps your cache directory clean, as old stale cache files are removed based on this timeout.

  • left / right delimiter and tag name
    These settings allow you to change the keyword GeSHify looks for. A setting of “{” as left, “}” as right delimiter and “highlight” as tag name causes GeSHify to highlight code between {highlight} and {/highlight}.

  • encoding
    Sets the encoding setting of GeSHi. Valid values are those valid for the PHP function htmlentities.

  • check for updates
    Allows GeSHify to check for updates online. Requires LG Addon Updater to be installed and activated. Update notifications will be displayed on the control panel home page.

  • GeSHi version
    Version of GeSHi to use. Unless you really know what you're doing, you should stick to the stable version 1.0. Note that GeSHi 1.1 is not complete and misses some features, e.g. line numbering.

  • default code language
    Useful to change ExpressionEngine's [code]-tag's behavior when overwriting it.

  • default line number style
    “normal” for normal line numbers, “none” for no line numbers, “fancy” followed by a number for every nth line number highlighted in different color.

  • default keyword links
    Whether to enable linking of keywords to language documentation by default.

Tag Syntax

day-to-day usage

GeSHify hooks into ExpressionEngine's typography_parse_type_* extension hooks, which means you can use it at every point, where text comes from the database and is printed to the website. Hence, GeSHify can be used in weblog entries, comments, forum posts and probably in other extensions, too.

To trigger GeSHify, place your source code between the tags you configured in the settings panel in your post. By default, these tags are [code] and [/code].

The tag supports HTML attribute-style arguments. For example, you can change the language used for this specific code block, by specifying the lang attribute: [code lang=java].

As of version 0.3.9 and higher, all attribute values can be quoted as you would in HTML, that is with single or double quotes. Note that the code will remain backwards compatible (i.e. specifying arguments without quotes will be supported).

Possible arguments for the code tag are:

  • code language
    syntax: lang=$languageIdentifier
    example: lang=java

    Valid values for $languageIdentifier are those valid for GeSHi. Check the GeSHi website for these values.

  • line number style
    syntax: line=none|normal|fancy$number
    example: line=fancy5

    Specify either “none”, “normal” or “fancy” followed by a number to disable line numbers, enable normal line numbers or enable fancy line numbers, where each $numberth line number is highlighted in a special color.

  • first line number
    syntax: start=$number
    example: start=10

    Use $number as first line number. Useful to split one file into multiple snippets while preserving consistent line numbers.

  • strict mode
    syntax: strict=$boolean
    example: strict=true

    Whether to use GeSHi strict mode. Valid values for $boolean are “true”, “false”, “1” and “0”.

  • keyword linking
    syntax: keyword_links=$boolean
    example: keyword_links=false

    Whether to link language keywords to documentation. Valid values for $boolean are “true”, “false”, “1” and “0”.

  • HTML id attribute
    syntax: overall_id=$string
    example: overall_id=heapsort

    HTML id attribute GeSHi adds to it's wrapper. Useful to address the highlighted source from JavaScript or CSS.

  • HTML class attribute
    syntax: overall_class=$string
    example: overall_class=sorting_algorithms

    HTML class attribute GeSHi adds to it's wrapper. Useful to address the highlighted source from JavaScript or CSS.