Gitit

Gitit is a wiki program written in Haskell. It uses Happstack for the web server and pandoc for markup processing. Pages and uploaded files are stored in a git or darcs repository and may be modified either by using the VCS's command-line tools or through the wiki's web interface. By default, pandoc's extended version of markdown is used as a markup language, but reStructuredText can also be used. Pages can be exported in a number of different formats, including LaTeX, RTF, OpenOffice ODT, and MediaWiki markup. Gitit can be configured to display TeX math (using jsMath) and highlighted source code (using highlighting-kate).

Getting started

Compiling and installing gitit

You'll need the GHC compiler and the cabal-install tool. GHC can be downloaded here. Note that, starting with release 0.5, GHC 6.10 or higher is required. For cabal-install on *nix, follow the [quick install][] instructions.

[quick install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick Installation on Unix [pcre]: http://www.pcre.org/

If you want the syntax highlighting feature, you need to make sure that pandoc is compiled with support for it. First, make sure your system has the [pcre][] library installed. Then:

cabal update
cabal install -fhighlighting pandoc gitit

If you don't care about highlighting support, you can just do:

cabal install gitit

These commands will install the latest released version of gitit. To install a version of gitit checked out from the repository, change to the gitit directory and type:

cabal install

The cabal tool will automatically install all of the required haskell libraries. If all goes well, by the end of this process, the latest release of gitit will be installed in your local .cabal directory. You can check this by trying:

gitit --version

If that doesn't work, check to see that gitit is in your local cabal-install executable directory (usually ~/.cabal/bin). And make sure ~/.cabal/bin is in your system path.

Optional plugins support

Plugins are small Haskell programs that transform a wiki page after it has been converted from Markdown or RST. See the example plugins in the plugins directory. To enable a plugin, include the path to the plugin (or its module name) in the pluginModules field of a configuration file. (If the plugin name starts with Gitit.Plugin., gitit will assume that the plugin is an installed module and will not look for a source file.)

The gitit executable will be much larger if plugins support is compiled in. Plugin support is disabled by default. To enable support for plugins, pass the plugins flag to Cabal:

cabal install gitit -fplugins

Note also that if you compile gitit for executable profiling, attempts to load plugins will result in "internal error: PAP object entered!"

Running gitit

To run gitit, you'll need git in your system path. Check this by doing

git --version

You should also make sure that you are using a UTF-8 locale. (To check this, type locale.)

Switch to the directory where you want to run gitit. This should be a directory where you have write access, since two directories, static and wikidata, and two files, gitit-users and template.html, will be created here. To start gitit, just type:

gitit

If all goes well, gitit will do the following:

1. Create a git repository, wikidata, and add a default front page.
2. Create a static directory containing the scripts and CSS used by gitit.
3. Create a template.html file containing an (HStringTemplate) template for wiki pages.
4. Start a web server on port 5001.

Check that it worked: open a web browser and go to http://localhost:5001.

Configuration options

You can set some configuration options when starting gitit, using the option -f [filename]. A configuration file takes the following form:

Config {
repository          = Git "wikidata",
defaultPageType     = Markdown,
userFile            = "gitit-users",
templateFile        = "template.html",
staticDir           = "static",
pluginModules       = ["plugins/DotPlugin"],
tableOfContents     = False,
maxUploadSize       = 100000,
portNumber          = 5001,
debugMode           = True,
frontPage           = "Front Page",
noEdit              = ["Help", "Front Page"],
noDelete            = ["Help", "Front Page"],
accessQuestion      = Just ("Enter the access code (to request an access code, contact [email protected]):", ["abcd"]),
useRecaptcha        = False,
recaptchaPublicKey  = "",
recaptchaPrivateKey = "",
maxCacheSize        = 2 * 1024 * 1024,
mimeTypesFile       = "/etc/mime.types"
}

• repository specifies the type and (relative) path of the repository in which the wiki's pages will be stored. If it does not exist, gitit will create it on startup. Supported repository types are Git and Darcs.

• defaultPageType is the type of markup used to interpret pages in the wiki. Two values are currently supported: Markdown and RST. If Markdown is selected, pandoc's syntax extensions (for footnotes, delimited code blocks, etc.) will be enabled. Note that pandoc's reStructuredText parser is not complete, so some pages may not be rendered correctly if RST is selected.

• userFile is a file containing user login information (with hashed passwords). If it does not exist, gitit will start with an empty list of users. Gitit will write a new userFile on shutdown.

• templateFile is a file containing an HTML template for the wiki pages. If it does not exist, gitit will create a default template. (For most purposes, this can be used just as it is, but some users may wish to customize the look of their wiki.) templateFile is an HStringTemplate template.

• staticDir is the (relative) path of a directory in which static content (javascript, CSS, images) is stored. If it does not exist, gitit will create it on startup.

• pluginModules is a list (possibly empty) of plugin modules to load.

• tableOfContents is either False or True. If it is True, a table of contents (derived from the page's headers) will appear on each page.

• maxUploadSize (in bytes) sets a limit to the size of file uploads.

• portNumber is the number of the port on which the wiki will be served.

• debugMode is either True or False. If it is True, debug information will be printed to the console when gitit is running.

• frontPage is the name of the page that is designated as the "front" or "entrance" page of the wiki. Any page may be designated.

• noEdit is a list of pages that cannot be edited.

• noDelete is a list of pages that cannot be deleted.

• accessQuestion provides primitive access control. It is either Nothing, in which case anyone will be allowed to create an account and edit wiki pages, or Just (question, [answer1, answer2, ...]), where question is a prompt that will be displayed when a user tries to create an account, and answer1, answer2, ... are the valid responses. The user must provide a valid response in order to create an account.

• useRecaptcha is either True or False. It specifies whether to use the reCAPTCHA service to provide captchas for user registration.

• recaptchaPublicKey and recaptchaPrivateKey are reCAPTCHA keys, which can be obtained free of charge at http://recaptcha.net/api/getkey. The values of these fields are ignored if useRecaptcha is set to False.

• maxCacheSize is the maximum size of the in-memory page cache (in bytes).

• mimeTypesFile is the path of a file containing mime type associations. Each line of the file should contain a mime type, followed by some space, followed by a space-separated list of file extensions that map to that mime type. If the file is not found, some simple defaults will be used.

The easiest way to create a custom configuration file is to dump the default configuration and modify it:

gitit --print-default-config > myconf.hs
# edit myconf.hs

Configuring gitit

The static directory

If there is no wiki page or uploaded file corresponding to a request, gitit always looks last in the static directory. So, for example, a file foo.jpg in the img subdirectory of the static directory will be accessible at the url /img/foo.jpg. Pandoc creates three subdirectories of static, css, img, and js, which include the icons, stylesheets, and javascripts it uses.

Note: if you set staticDir to be a subdirectory of repositoryPath, and then add the files in the static directory to your repository, you can ensure that others who clone your wiki repository get these files as well. It will not be possible to modify these files using the web interface, but they will be modifiable via git.

Changing the theme

To change the look of the wiki, modify screen.css in static/css. To change the look of printed pages, modify print.css. The logo picture can be changed by copying a new PNG file to static/img/logo.png. For more radical changes, one can modify template.html.

Adding support for math

Gitit is designed to work with jsMath to display LaTeX math in HTML. Download jsMath and jsMath Image Fonts from the jsMath download page. You'll have two .zip archives. Unzip them both in the static/js directory (a new subdirectory, jsMath, will be created). You can test to see if math is working properly by clicking "help" on the top navigation bar and looking for the math example (the quadratic formula). Note that if you copied the jsMath directory into static after starting gitit, you will have to restart gitit for the change to be noticed. Gitit checks for the existence of the jsMath files when it starts, and will not include links to them unless they exist.

To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:

Here is a formula:  $\frac{1}{\sqrt{c^2}}$

You can write display math by enclosing it in double dollar signs:

$$\frac{1}{\sqrt{c^2}}$$

Highlighted source code

If gitit was compiled against a version of pandoc that has highlighting support (see above), you can get highlighted source code by using delimited code blocks:

~~~ {.haskell .numberLines}
qsort []     = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
               qsort (filter (>= x) xs) 
~~~

To see what languages are available:

pandoc -v

Accessing the wiki via git

All the pages and uploaded files are stored in a git repository. By default, this lives in the wikidata directory (though this can be changed through configuration options). So you can interact with the wiki using git command line tools:

git clone ssh://my.server.edu/path/of/wiki/wikidata
cd wikidata
vim Front\ Page.page  # edit the page
git commit -m "Added message about wiki etiquette" Front\ Page.page
git push 

If you now look at the Front Page on the wiki, you should see your changes reflected there. Note that the pages all have the extension .page.

Wiki links and formatting

For instructions on editing pages and creating links, see the "Help" page.

Gitit interprets links with empty URLs as wikilinks. Thus, in markdown pages, [Front Page]() creates an internal wikilink to the page Front Page. In reStructuredText pages, `Front Page <>`_ has the same effect.

Character encodings

Gitit assumes that the page files (stored in the git repository) are encoded as UTF-8. Even page names may be UTF-8 if the file system supports this. You should use a UTF-8 locale when running gitit.

Reporting bugs

Bugs may be reported (and feature requests filed) at http://code.google.com/p/gitit/issues/list.

Acknowledgements

Gwern Branwen helped to optimize Gitit. Simon Michael contributed the patch for RST support.

The visual layout is shamelessly borrowed from Wikipedia.

The stylesheets are influenced by Wikipedia's stylesheets and by the bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in img/icons come from bluetrip as well.