Gitit

Gitit is a wiki program written in Haskell. It uses HAppS for the web server and session state, git for storage, history, search, diffs, and merging, and pandoc for markup processing. Pages can be added, changed, and removed either on the web or using git's command-line tools. Gitit uses pandoc's extended version of markdown as its markup language.

Getting started

Compiling and installing gitit

You'll need the GHC compiler and the cabal-install tool. GHC can be downloaded here. 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 install pandoc -fhighlighting

You can skip this step if you don't care about highlighting support.

You can now install the latest release of gitit:

cabal update
cabal install 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.

Running gitit

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

git --version

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, 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. 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 {
repositoryPath  = "wikidata",
staticDir       = "static",
wikiBanner      = "<img src=\"/images/bann.png\" alt=\"banner\"",
wikiTitle       = "Wiki",
wikiFooter      = "Powered by Gitit",
tableOfContents = False,
maxUploadSize   = 100000,
portNumber      = 5001,
passwordSalt    = "l91snthoae8eou2340987",
debugMode       = True,
noEdit          = ["Help"],
noDelete        = ["Help", "Front Page"],
accessQuestion  = Just ("Enter the access code (to request a code, contact me@foo.bar.com):", ["abcd"])
}

For the most part, these options should be self-explanatory.

• The wikiBanner will be inserted before the top navigation bar on pages, and can be used to include a banner or wiki title. It is raw HTML. Similarly, the wikiFooter is raw HTML that will be inserted at the bottom of the page.
• The tableOfContents boolean determines whether a table of contents, derived from the page's headers, will be included for every page.
• maxUploadSize (in bytes) limits the size of pages and uploads.
• The passwordSalt is used to encrypt passwords and should be changed for every new site.
• debugMode causes diagnostic information to be printed to the console.
• noEdit is a list of pages that cannot be edited using the web interface. (They may still be edited via git, by those with access to the repository.)
• noDelete is a list of pages that cannot be deleted using the web interface.
• The accessQuestion is either Nothing (in which case anyone will be allowed to register for an account) or Just (question, [ans1, ans2, ...]) (in which case anyone who registers must first answer the question with one of the provided answers). One can deter automated spammers by using an accessQuestion with an easy and obvious answer. Or one can use an accessQuestion to limit those who can edit a wiki to a trusted group.

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 images subdirectory of the static directory will be accessible at the url /images/foo.jpg. Pandoc creates two subdirectories of static, stylesheets and javascripts, which include the CSS and scripts it uses.

Changing the theme

To change the look of the wiki, modify gitit.css in static/stylesheets.

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/javascripts 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).

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.

Reporting bugs

There is no bug tracker as yet, so report bugs directly to the author, jgm at berkeley . edu

Acknowledgements

I borrowed some ideas about visual layout from Jeff Barczewski's fork of Simon Rozet's git-wiki.

The code in Gitit/State.hs is based on http://hpaste.org/5957 by mightybyte, as revised by dbpatterson.