The gitit package

Gitit is a wiki backed by a git, darcs, or mercurial
filestore. Pages and uploaded files can be modified either
directly via the VCS's command-line tools or through
the wiki's web interface. Pandoc is used for markup
processing, so pages may be written in
(extended) markdown, reStructuredText, LaTeX, HTML,
or literate Haskell, and exported in ten different
formats, including LaTeX, ConTeXt, DocBook, RTF,
OpenOffice ODT, and MediaWiki markup.

Maintainer's Corner

Readme for gitit-0.10.5

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, darcs, or mercurial 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, LaTeX, HTML,
DocBook, or Emacs Org-mode markup 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
texmath) and highlighted source code (using highlighting-kate).

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 syntax highlighting support

If pandoc was compiled with optional syntax highlighting support,
this will be available in gitit too. This feature is recommended
if you plan to display source code on your wiki.

Highlighting support requires the pcre library, so make sure that
is installed before continuing.

To install gitit with highlighting support, first ensure that pandoc
is compiled with highlighting support, then install gitit as above:

cabal install pandoc -fhighlighting --reinstall
cabal install gitit

Running gitit

To run gitit, you'll need git in your system path. (Or darcs or
hg, if you're using darcs or mercurial to store the wiki data.)

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. So you should make sure that you are using a UTF-8 locale
when running gitit. (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 three directories, static,
templates, and wikidata, and two files, gitit-users and gitit.log,
will be created here. To start gitit, just type:

gitit

If all goes well, gitit will do the following:

Create a git repository, wikidata, and add a default front page.

Create a static directory containing files to be treated as
static files by gitit.

Page metadata

The metadata block consists of a list of key-value pairs, each on a
separate line. If needed, the value can be continued on one or more
additional line, which must begin with a space. (This is illustrated by
the "title" example above.) The metadata block must begin with a line
--- and end with a line ... optionally followed by one or more blank
lines. (The metadata block is a valid YAML document, though not all YAML
documents will be valid metadata blocks.)

Currently the following keys are supported:

format
: Overrides the default page type as specified in the configuration file.
Possible values are markdown, rst, latex, html, markdown+lhs,
rst+lhs, latex+lhs. (Capitalization is ignored, so you can also
use LaTeX, HTML, etc.) The +lhs variants indicate that the page
is to be interpreted as literate Haskell. If this field is missing,
the default page type will be used.

categories
: A space or comma separated list of categories to which the page belongs.

toc
: Overrides default setting for table-of-contents in the configuration file.
Values can be yes, no, true, or false (capitalization is ignored).

title
: By default the displayed page title is the page name. This metadata element
overrides that default.

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:

Configuring and customizing gitit

Configuration options

If this option is not used, gitit will use a default configuration.
To get a copy of the default configuration file, which you
can customize, just type:

gitit --print-default-config > my.conf

The default configuration file is documented with comments throughout.

The static directory

On receiving a request, gitit always looks first in the static
directory (or in whatever directory is specified for static-dir in
the configuration file). If a file corresponding to the request is
found there, it is served immediately. If the file is not found in
static, gitit next looks in the static subdirectory of gitit's data
file ($CABALDIR/share/gitit-x.y.z/data). This is where default css,
images, and javascripts are stored. If the file is not found there
either, gitit treats the request as a request for a wiki page or wiki
command.

So, you can throw anything you want to be served statically (for
example, a robots.txt file or favicon.ico) in the static
directory. You can override any of gitit's default css, javascript, or
image files by putting a file with the same relative path in static.
Note that gitit has a default robots.txt file that excludes all
URLs beginning with /_.

Note: if you set static-dir to be a subdirectory of repository-path,
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.

Using a VCS other than git

By default, gitit will store wiki pages in a git repository in the
wikidata directory. If you'd prefer to use darcs instead of git,
you need to add the following field to the configuration file:

repository-type: Darcs

If you'd prefer to use mercurial, add:

repository-type: Mercurial

This program may be called "darcsit" instead of "gitit" when a darcs
backend is used.

Note: we recommend that you use gitit/darcsit with darcs version
2.3.0 or greater. If you must use an older version of darcs, then
you need to compile the filestore library without the (default)
maxcount flag, before (re)installing gitit:

Otherwise you will get an error when you attempt to access your
repository.

Changing the theme

To change the look of the wiki, you can modify custom.css in
static/css.

To change the look of printed pages, copy gitit's default print.css
to static/css and modify it.

The logo picture can be changed by copying a new PNG file to
static/img/logo.png. The default logo is 138x155 pixels.

To change the footer, modify templates/footer.st.

For more radical changes, you can override any of the default
templates in $CABALDIR/share/gitit-x.y.z/data/templates by copying
the file into templates, modifying it, and restarting gitit. The
page.st template is the master template; it includes the others.
Interpolated variables are surrounded by $s, so literal $ must
be backslash-escaped.

Adding support for math

To write math on a markdown-formatted 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}}$$

Gitit can display TeX math in three different ways, depending on the
setting of math in the configuration file:

mathml (default): Math will be converted to MathML using
texmath. This method works with IE+mathplayer, Firefox, and
Opera, but not Safari.

jsMath: Math will be rendered using the jsMath javascript.
If you want to use this method, 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). This works with all
browsers, but is slower and not as nice looking as MathML.

raw: Math will be rendered as raw LaTeX codes.

Restricting access

If you want to limit account creation on your wiki, the easiest way to do this
is to provide an access-question in your configuration file. (See the commented
default configuration file.) Nobody will be able to create an account without
knowing the answer to the access question.

Another approach is to use HTTP authentication. (See the config file comments on
authentication-method.)

Authentication through github

If you want to authenticate the user from github through oauth2, you need to
register your app with github to obtain a OAuth client secret and add the
following section to your configuration file:

Plugins

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

Plugin support is enabled by default. However, plugin support makes
the gitit executable considerably larger and more memory-hungry.
If you don't need plugins, you may want to compile gitit without plugin
support. To do this, unset the plugins Cabal flag:

cabal install --reinstall gitit -f-plugins

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

Accessing the wiki through 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:

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.

If you are using the darcs or mercurial backend, the commands will
be slightly different. See the documentation for your VCS for
details.

Performance

Caching

By default, gitit does not cache content. If your wiki receives a lot of
traffic or contains pages that are slow to render, you may want to activate
caching. To do this, set the configuration option use-cache to yes.
By default, rendered pages, highlighted source files, and exported PDFs
will be cached in the cache directory. (Another directory can be
specified by setting the cache-dir configuration option.)

Cached pages are updated when pages are modified using the web
interface. They are not updated when pages are modified directly through
git or darcs. However, the cache can be refreshed manually by pressing
Ctrl-R when viewing a page, or by sending an HTTP GET or POST request to
/_expire/path/to/page, where path/to/page is the name of the page to
be expired.

Users who frequently update pages using git or darcs may wish to add a
hook to the repository that makes the appropriate HTTP request to expire
pages when they are updated. To facilitate such hooks, the gitit cabal
package includes an executable expireGititCache. Assuming you are
running gitit at port 5001 on localhost, and the environment variable
CHANGED_FILES contains a list of the files that have changed, you can
expire their cached versions using

This program will return a success status (0) if the page has been
successfully expired (or if it was never cached in the first place),
and a failure status (> 0) otherwise.

The cache is persistent through restarts of gitit. To expire all cached
pages, simply remove the cache directory.

Idle

By default, GHC's runtime will repeatedly attempt to collect garbage
when an executable like Gitit is idle. This means that gitit will, after
the first page request, never use 0% CPU time and sleep, but will use
~1%. This can be bad for battery life, among other things.

To fix this, one can disable the idle-time GC with the runtime flag
-I0:

gitit -f my.conf +RTS -I0 -RTS

Using gitit with apache

Most users who run a public-facing gitit will want gitit to appear
at a nice URL like http://wiki.mysite.com or
http://mysite.com/wiki rather than http://mysite.com:5001.
This can be achieved using apache's mod_proxy.

Proxying to http://wiki.mysite.com

Set up your DNS so that http://wiki.mysite.com maps to
your server's IP address. Make sure that the mod_proxy, mod_proxy_http and mod_rewrite modules are
loaded, and set up a virtual host with the following configuration:

Proxying to http://mysite.com/wiki

Make sure the mod_proxy, mod_headers, mod_proxy_http,
and mod_proxy_html modules are loaded. mod_proxy_html
is an external module, which can be obtained here
(http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
occur in web pages. Here we will use it to rewrite gitit's links so that
they all begin with /wiki/.

First, tell gitit not to compress pages, since mod_proxy_html needs
uncompressed pages to parse. You can do this by setting the gitit
configuration option

compress-responses: no

Second, modify the link in the reset-password-message in the
configuration file: instead of

http://$hostname$:$port$$resetlink$

set it to

http://$hostname$/wiki$resetlink$

Restart gitit.

Now add the following lines to the apache configuration file for the
mysite.com server:

Using gitit as a library

By importing the module Network.Gitit, you can include a gitit wiki
(or several of them) in another happstack application. There are some
simple examples in the haddock documentation for Network.Gitit.

mightybyte suggested making gitit available as a library,
and contributed a patch to ifLoggedIn that was needed to
make gitit usable with a custom authentication scheme.

I am especially grateful to the darcs team for using darcsit for
their public-facing wiki. This has helped immensely in identifying
issues and improving performance.

Gitit's default 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.