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. Gitit can be configured to display TeX math (using texmath) and highlighted source code (using skylighting).

Other features include

• plugins: dynamically loaded page transformations written in Haskell (see "Network.Gitit.Interface")

• categories

• TeX math

• syntax highlighting of source code files and code snippets.

• caching

• Atom feeds (site-wide and per-page)

• a library, "Network.Gitit", that makes it simple to include a gitit wiki in any happstack application

Getting started

Compiling and installing gitit

The most reliable way to install gitit from source is to get the stack tool. Then clone the gitit repository and use stack to install:

git clone https://github.com/jgm/gitit
cd gitit
stack install

Alternatively, instead of using stack, you can get the Haskell Platform and do the following:

cabal update
cabal install gitit

This 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.

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:

1. Create a git repository, wikidata, and add a default front page.
2. Create a static directory containing files to be treated as static files by gitit.
3. Create a templates directory containing HStringTemplate templates 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.

You can control the port that gitit runs on using the -p option: gitit -p 4000 will start gitit on port 4000. Additional runtime options are described by gitit -h.

Using gitit

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.

If you want to link to a directory listing for a subdirectory, use a trailing slash: [foo/bar/]() creates a link to the directory for foo/bar.

Page metadata

Pages may optionally begin with a metadata block. Here is an example:

---
format: latex+lhs
categories: haskell math
toc: no
title: Haskell and
  Category Theory
...

\section{Why Category Theory?}

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:

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗