wiki/Gitit User’s Guide.page

---
format: DocBook
...

<sect1 id="gitit">
  <title>Gitit</title>
  <para>
    Gitit is a wiki program written in Haskell. It uses
    <ulink url="http://happstack.com">Happstack</ulink> for the web
    server and
    <ulink url="http://johnmacfarlane.net/pandoc">pandoc</ulink> for
    markup processing. Pages and uploaded files are stored in a
    <ulink url="http://git.or.cz">git</ulink>,
    <ulink url="http://darcs.net">darcs</ulink>, or
    <ulink url="http://mercurial.selenic.com/">mercurial</ulink>
    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
    <ulink url="http://github.com/jgm/texmath/tree/master">texmath</ulink>)
    and highlighted source code (using
    <ulink url="http://johnmacfarlane.net/highlighting-kate/">highlighting-kate</ulink>).
  </para>
  <para>
    Other features include
  </para>
  <itemizedlist>
    <listitem>
      <para>
        plugins: dynamically loaded page transformations written in
        Haskell (see <quote>Network.Gitit.Interface</quote>)
      </para>
    </listitem>
    <listitem>
      <para>
        categories
      </para>
    </listitem>
    <listitem>
      <para>
        TeX math
      </para>
    </listitem>
    <listitem>
      <para>
        syntax highlighting of source code files and code snippets
        (using highlighting-kate)
      </para>
    </listitem>
    <listitem>
      <para>
        caching
      </para>
    </listitem>
    <listitem>
      <para>
        Atom feeds (site-wide and per-page)
      </para>
    </listitem>
    <listitem>
      <para>
        a library, <quote>Network.Gitit</quote>, that makes it simple to
        include a gitit wiki in any happstack application
      </para>
    </listitem>
  </itemizedlist>
  <para>
    You can see a running demo at
    <ulink url="http://gitit.johnmacfarlane.net">http://gitit.johnmacfarlane.net</ulink>.
  </para>
</sect1>
<sect1 id="getting-started">
  <title>Getting started</title>
  <sect2 id="compiling-and-installing-gitit">
    <title>Compiling and installing gitit</title>
    <para>
      You’ll need the
      <ulink url="http://www.haskell.org/ghc/">GHC</ulink> compiler and
      the
      <ulink url="http://hackage.haskell.org/trac/hackage/wiki/CabalInstall">cabal-install</ulink>
      tool. GHC can be downloaded
      <ulink url="http://www.haskell.org/ghc/">here</ulink>. Note that,
      starting with release 0.5, GHC 6.10 or higher is required. For
      <ulink url="http://hackage.haskell.org/trac/hackage/wiki/CabalInstall">cabal-install</ulink>
      on *nix, follow the
      <ulink url="http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick+Installation+on+Unix">quick
      install</ulink> instructions.
    </para>
    <para>
      Once you’ve got cabal-install, installing gitit is trivial:
    </para>
    <programlisting>
cabal update
cabal install gitit
</programlisting>
    <para>
      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:
    </para>
    <programlisting>
cabal install
</programlisting>
    <para>
      The <literal>cabal</literal> 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 <literal>.cabal</literal> directory. You can check this
      by trying:
    </para>
    <programlisting>
gitit --version
</programlisting>
    <para>
      If that doesn’t work, check to see that <literal>gitit</literal>
      is in your local cabal-install executable directory (usually
      <literal>~/.cabal/bin</literal>). And make sure
      <literal>~/.cabal/bin</literal> is in your system path.
    </para>
  </sect2>
  <sect2 id="optional-syntax-highlighting-support">
    <title>Optional syntax highlighting support</title>
    <para>
      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.
    </para>
    <para>
      Highlighting support requires the
      <ulink url="http://www.pcre.org/">pcre</ulink> library, so make
      sure that is installed before continuing.
    </para>
    <para>
      To install gitit with highlighting support, first ensure that
      pandoc is compiled with highlighting support, then install gitit
      as above:
    </para>
    <programlisting>
cabal install pandoc -fhighlighting --reinstall
cabal install gitit
</programlisting>
  </sect2>
  <sect2 id="running-gitit">
    <title>Running gitit</title>
    <para>
      To run gitit, you’ll need <literal>git</literal> in your system
      path. (Or <literal>darcs</literal> or <literal>hg</literal>, if
      you’re using darcs or mercurial to store the wiki data.)
    </para>
    <para>
      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
      <literal>locale</literal>.)
    </para>
    <para>
      Switch to the directory where you want to run gitit. This should
      be a directory where you have write access, since three
      directories, <literal>static</literal>,
      <literal>templates</literal>, and <literal>wikidata</literal>, and
      two files, <literal>gitit-users</literal> and
      <literal>gitit.log</literal>, will be created here. To start
      gitit, just type:
    </para>
    <programlisting>
gitit
</programlisting>
    <para>
      If all goes well, gitit will do the following:
    </para>
    <orderedlist numeration="arabic" spacing="compact">
      <listitem>
        <para>
          Create a git repository, <literal>wikidata</literal>, and add
          a default front page.
        </para>
      </listitem>
      <listitem>
        <para>
          Create a <literal>static</literal> directory containing files
          to be treated as static files by gitit.
        </para>
      </listitem>
      <listitem>
        <para>
          Create a <literal>templates</literal> directory containing
          HStringTemplate templates for wiki pages.
        </para>
      </listitem>
      <listitem>
        <para>
          Start a web server on port 5001.
        </para>
      </listitem>
    </orderedlist>
    <para>
      Check that it worked: open a web browser and go to
      <ulink url="http://localhost:5001">http://localhost:5001</ulink>.
    </para>
    <para>
      You can control the port that gitit runs on using the
      <literal>-p</literal> option: <literal>gitit -p 4000</literal>
      will start gitit on port 4000. Additional runtime options are
      described by <literal>gitit -h</literal>.
    </para>
  </sect2>
</sect1>
<sect1 id="using-gitit">
  <title>Using gitit</title>
  <sect2 id="wiki-links-and-formatting">
    <title>Wiki links and formatting</title>
    <para>
      For instructions on editing pages and creating links, see the
      <quote>Help</quote> page.
    </para>
    <para>
      Gitit interprets links with empty URLs as wikilinks. Thus, in
      markdown pages, <literal>[Front Page]()</literal> creates an
      internal wikilink to the page <literal>Front Page</literal>. In
      reStructuredText pages, <literal>`Front Page &lt;&gt;`_</literal>
      has the same effect.
    </para>
    <para>
      If you want to link to a directory listing for a subdirectory, use
      a trailing slash: <literal>[foo/bar/]()</literal> creates a link
      to the directory for <literal>foo/bar</literal>.
    </para>
  </sect2>
  <sect2 id="page-metadata">
    <title>Page metadata</title>
    <para>
      Pages may optionally begin with a metadata block. Here is an
      example:
    </para>
    <programlisting>
---
format: latex+lhs
categories: haskell math
toc: no
title: Haskell and
  Category Theory
...

\section{Why Category Theory?}
</programlisting>
    <para>
      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 <quote>title</quote> example above.) The
      metadata block must begin with a line <literal>---</literal> and
      end with a line <literal>...</literal> 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.)
    </para>
    <para>
      Currently the following keys are supported:
    </para>
    <variablelist spacing="compact">
      <varlistentry>
        <term>
          format
        </term>
        <listitem>
          <para>
            Overrides the default page type as specified in the
            configuration file. Possible values are
            <literal>markdown</literal>, <literal>rst</literal>,
            <literal>latex</literal>, <literal>html</literal>,
            <literal>markdown+lhs</literal>, <literal>rst+lhs</literal>,
            <literal>latex+lhs</literal>. (Capitalization is ignored, so
            you can also use <literal>LaTeX</literal>,
            <literal>HTML</literal>, etc.) The <literal>+lhs</literal>
            variants indicate that the page is to be interpreted as
            literate Haskell. If this field is missing, the default page
            type will be used.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          categories
        </term>
        <listitem>
          <para>
            A space or comma separated list of categories to which the
            page belongs.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          toc
        </term>
        <listitem>
          <para>
            Overrides default setting for table-of-contents in the
            configuration file. Values can be <literal>yes</literal>,
            <literal>no</literal>, <literal>true</literal>, or
            <literal>false</literal> (capitalization is ignored).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          title
        </term>
        <listitem>
          <para>
            By default the displayed page title is the page name. This
            metadata element overrides that default.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>
  <sect2 id="highlighted-source-code">
    <title>Highlighted source code</title>
    <para>
      If gitit was compiled against a version of pandoc that has
      highlighting support (see above), you can get highlighted source
      code by using
      <ulink url="http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks">delimited
      code blocks</ulink>:
    </para>
    <programlisting>
~~~ {.haskell .numberLines}
qsort []     = []
qsort (x:xs) = qsort (filter (&lt; x) xs) ++ [x] ++
               qsort (filter (&gt;= x) xs) 
~~~
</programlisting>
    <para>
      To see what languages your pandoc was compiled to highlight:
    </para>
    <programlisting>
pandoc -v
</programlisting>
  </sect2>
</sect1>
<sect1 id="configuring-and-customizing-gitit">
  <title>Configuring and customizing gitit</title>
  <sect2 id="configuration-options">
    <title>Configuration options</title>
    <para>
      Use the option <literal>-f [filename]</literal> to specify a
      configuration file:
    </para>
    <programlisting>
gitit -f my.conf
</programlisting>
    <para>
      The configuation can be splitted between several files:
    </para>
    <programlisting>
gitit -f my.conf -f additional.conf
</programlisting>
    <para>
      One use case is to keep sensible part of the configuration outside
      of a SCM (oauth client secret for example).
    </para>
    <para>
      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:
    </para>
    <programlisting>
gitit --print-default-config &gt; my.conf
</programlisting>
    <para>
      The default configuration file is documented with comments
      throughout.
    </para>
  </sect2>
  <sect2 id="the-static-directory">
    <title>The <literal>static</literal> directory</title>
    <para>
      On receiving a request, gitit always looks first in the
      <literal>static</literal> directory (or in whatever directory is
      specified for <literal>static-dir</literal> 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
      <literal>static</literal>, gitit next looks in the
      <literal>static</literal> subdirectory of gitit’s data file
      (<literal>$CABALDIR/share/gitit-x.y.z/data</literal>). 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.
    </para>
    <para>
      So, you can throw anything you want to be served statically (for
      example, a <literal>robots.txt</literal> file or
      <literal>favicon.ico</literal>) in the <literal>static</literal>
      directory. You can override any of gitit’s default css,
      javascript, or image files by putting a file with the same
      relative path in <literal>static</literal>. Note that gitit has a
      default <literal>robots.txt</literal> file that excludes all URLs
      beginning with <literal>/_</literal>.
    </para>
    <para>
      Note: if you set <literal>static-dir</literal> to be a
      subdirectory of <literal>repository-path</literal>, 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.
    </para>
  </sect2>
  <sect2 id="using-a-vcs-other-than-git">
    <title>Using a VCS other than git</title>
    <para>
      By default, gitit will store wiki pages in a git repository in the
      <literal>wikidata</literal> directory. If you’d prefer to use
      darcs instead of git, you need to add the following field to the
      configuration file:
    </para>
    <programlisting>
repository-type: Darcs
</programlisting>
    <para>
      If you’d prefer to use mercurial, add:
    </para>
    <programlisting>
repository-type: Mercurial
</programlisting>
    <para>
      This program may be called <quote>darcsit</quote> instead of
      <quote>gitit</quote> when a darcs backend is used.
    </para>
    <para>
      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:
    </para>
    <programlisting>
cabal install --reinstall filestore -f-maxcount
cabal install --reinstall gitit
</programlisting>
    <para>
      Otherwise you will get an error when you attempt to access your
      repository.
    </para>
  </sect2>
  <sect2 id="changing-the-theme">
    <title>Changing the theme</title>
    <para>
      To change the look of the wiki, you can modify
      <literal>custom.css</literal> in <literal>static/css</literal>.
    </para>
    <para>
      To change the look of printed pages, copy gitit’s default
      <literal>print.css</literal> to <literal>static/css</literal> and
      modify it.
    </para>
    <para>
      The logo picture can be changed by copying a new PNG file to
      <literal>static/img/logo.png</literal>. The default logo is
      138x155 pixels.
    </para>
    <para>
      To change the footer, modify
      <literal>templates/footer.st</literal>.
    </para>
    <para>
      For more radical changes, you can override any of the default
      templates in
      <literal>$CABALDIR/share/gitit-x.y.z/data/templates</literal> by
      copying the file into <literal>templates</literal>, modifying it,
      and restarting gitit. The <literal>page.st</literal> template is
      the master template; it includes the others. Interpolated
      variables are surrounded by <literal>$</literal>s, so
      <literal>literal $</literal> must be backslash-escaped.
    </para>
  </sect2>
  <sect2 id="adding-support-for-math">
    <title>Adding support for math</title>
    <para>
      To write math on a markdown-formatted wiki page, just enclose it
      in dollar signs, as in LaTeX:
    </para>
    <programlisting>
Here is a formula:  $\frac{1}{\sqrt{c^2}}$
</programlisting>
    <para>
      You can write display math by enclosing it in double dollar signs:
    </para>
    <programlisting>
$$\frac{1}{\sqrt{c^2}}$$
</programlisting>
    <para>
      Gitit can display TeX math in three different ways, depending on
      the setting of <literal>math</literal> in the configuration file:
    </para>
    <orderedlist numeration="arabic">
      <listitem>
        <para>
          <literal>mathml</literal> (default): Math will be converted to
          MathML using
          <ulink url="http://github.com/jgm/texmath/tree/master">texmath</ulink>.
          This method works with IE+mathplayer, Firefox, and Opera, but
          not Safari.
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>jsMath</literal>: Math will be rendered using the
          <ulink url="http://www.math.union.edu/~dpvc/jsmath/">jsMath</ulink>
          javascript. If you want to use this method, download
          <literal>jsMath</literal> and
          <literal>jsMath Image Fonts</literal> from the
          <ulink url="http://sourceforge.net/project/showfiles.php?group_id=172663">jsMath
          download page</ulink>. You’ll have two <literal>.zip</literal>
          archives. Unzip them both in the <literal>static/js</literal>
          directory (a new subdirectory, <literal>jsMath</literal>, will
          be created). This works with all browsers, but is slower and
          not as nice looking as MathML.
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>raw</literal>: Math will be rendered as raw LaTeX
          codes.
        </para>
      </listitem>
    </orderedlist>
  </sect2>
  <sect2 id="restricting-access">
    <title>Restricting access</title>
    <para>
      If you want to limit account creation on your wiki, the easiest
      way to do this is to provide an <literal>access-question</literal>
      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.
    </para>
    <para>
      Another approach is to use HTTP authentication. (See the config
      file comments on <literal>authentication-method</literal>.)
    </para>
  </sect2>
  <sect2 id="authentication-through-github">
    <title>Authentication through github</title>
    <para>
      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:
    </para>
    <programlisting>
[Github]
oauthclientid: 01239456789abcdef012
oauthclientsecret: 01239456789abcdef01239456789abcdef012394
oauthcallback: http://mysite/_githubCallback
oauthoauthorizeendpoint: https://github.com/login/oauth/authorize
oauthaccesstokenendpoint: https://github.com/login/oauth/access_token
## Uncomment if you are checking membership against an organization and change
## gitit-testorg to this organization:
# github-org: gitit-testorg
</programlisting>
    <para>
      The github authentication uses the scope
      <literal>user:email</literal>. This way, gitit gets the email of
      the user, and the commit can be assigned to the right author if
      the wikidata repository is pushed to github. Additionally, it uses
      <literal>read:org</literal> if you uses the option
      <literal>github-org</literal> to check membership against an
      organization.
    </para>
    <para>
      To push your repository to gitub after each commit, you can add
      the file <literal>post-commit</literal> with the content below in
      the .git/hooks directory of your wikidata repository.
    </para>
    <programlisting>
#!/bin/sh
git push origin master 2&gt;&gt; logit
</programlisting>
  </sect2>
</sect1>
<sect1 id="plugins">
  <title>Plugins</title>
  <para>
    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 <literal>plugins</literal> directory. To
    enable a plugin, include the path to the plugin (or its module name)
    in the <literal>plugins</literal> field of the configuration file.
    (If the plugin name starts with
    <literal>Network.Gitit.Plugin.</literal>, gitit will assume that the
    plugin is an installed module and will not look for a source file.)
  </para>
  <para>
    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 <literal>plugins</literal> Cabal
    flag:
  </para>
  <programlisting>
cabal install --reinstall gitit -f-plugins
</programlisting>
  <para>
    Note also that if you compile gitit for executable profiling,
    attempts to load plugins will result in <quote>internal error: PAP
    object entered!</quote>
  </para>
</sect1>
<sect1 id="accessing-the-wiki-through-git">
  <title>Accessing the wiki through git</title>
  <para>
    All the pages and uploaded files are stored in a git repository. By
    default, this lives in the <literal>wikidata</literal> directory
    (though this can be changed through configuration options). So you
    can interact with the wiki using git command line tools:
  </para>
  <programlisting>
git clone ssh://my.server.edu/path/of/wiki/wikidata
cd wikidata
vim Front\ Page.page  # edit the page
git commit -m &quot;Added message about wiki etiquette&quot; Front\ Page.page
git push
</programlisting>
  <para>
    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
    <literal>.page</literal>.
  </para>
  <para>
    If you are using the darcs or mercurial backend, the commands will
    be slightly different. See the documentation for your VCS for
    details.
  </para>
</sect1>
<sect1 id="performance">
  <title>Performance</title>
  <sect2 id="caching">
    <title>Caching</title>
    <para>
      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
      <literal>use-cache</literal> to <literal>yes</literal>. By
      default, rendered pages, highlighted source files, and exported
      PDFs will be cached in the <literal>cache</literal> directory.
      (Another directory can be specified by setting the
      <literal>cache-dir</literal> configuration option.)
    </para>
    <para>
      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 <literal>/_expire/path/to/page</literal>, where
      <literal>path/to/page</literal> is the name of the page to be
      expired.
    </para>
    <para>
      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
      <literal>expireGititCache</literal>. Assuming you are running
      gitit at port 5001 on localhost, and the environment variable
      <literal>CHANGED_FILES</literal> contains a list of the files that
      have changed, you can expire their cached versions using
    </para>
    <programlisting>
expireGititCache http://localhost:5001 $CHANGED_FILES
</programlisting>
    <para>
      Or you can specify the files directly:
    </para>
    <programlisting>
expireGititCache http://localhost:5001 &quot;Front Page.page&quot; foo/bar/baz.c
</programlisting>
    <para>
      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 (&gt; 0) otherwise.
    </para>
    <para>
      The cache is persistent through restarts of gitit. To expire all
      cached pages, simply remove the <literal>cache</literal>
      directory.
    </para>
  </sect2>
  <sect2 id="idle">
    <title>Idle</title>
    <para>
      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.
    </para>
    <para>
      To fix this, one can disable the idle-time GC with the runtime
      flag <literal>-I0</literal>:
    </para>
    <programlisting>
gitit -f my.conf +RTS -I0 -RTS
</programlisting>
  </sect2>
</sect1>
<sect1 id="using-gitit-with-apache">
  <title>Using gitit with apache</title>
  <para>
    Most users who run a public-facing gitit will want gitit to appear
    at a nice URL like <literal>http://wiki.mysite.com</literal> or
    <literal>http://mysite.com/wiki</literal> rather than
    <literal>http://mysite.com:5001</literal>. This can be achieved
    using apache’s <literal>mod_proxy</literal>.
  </para>
  <sect2 id="proxying-to-httpwiki.mysite.com">
    <title>Proxying to <literal>http://wiki.mysite.com</literal></title>
    <para>
      Set up your DNS so that <literal>http://wiki.mysite.com</literal>
      maps to your server’s IP address. Make sure that the
      <literal>mod_proxy</literal>, <literal>mod_proxy_http</literal>
      and <literal>mod_rewrite</literal> modules are loaded, and set up
      a virtual host with the following configuration:
    </para>
    <programlisting>
&lt;VirtualHost *&gt;
    ServerName wiki.mysite.com
    DocumentRoot /var/www/
    RewriteEngine On
    ProxyPreserveHost On
    ProxyRequests Off

    &lt;Proxy *&gt;
       Order deny,allow
       Allow from all
    &lt;/Proxy&gt;

    ProxyPassReverse /    http://127.0.0.1:5001
    RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]

    ErrorLog /var/log/apache2/error.log
    LogLevel warn

    CustomLog /var/log/apache2/access.log combined
    ServerSignature On

&lt;/VirtualHost&gt;
</programlisting>
    <para>
      Reload your apache configuration and you should be all set.
    </para>
  </sect2>
  <sect2 id="using-nginx-to-achieve-the-same">
    <title>Using nginx to achieve the same</title>
    <para>
      Drop a file called <literal>wiki.example.com.conf</literal> into
      <literal>/etc/nginx/conf.d</literal> (or where ever your
      distribution puts it).
    </para>
    <programlisting>
server {
    listen 80;
    server_name wiki.example.com
    location / {
        proxy_pass        http://127.0.0.1:5001/;
        proxy_set_header  X-Real-IP  $remote_addr;
        proxy_redirect off;
    }
    access_log /var/log/nginx/wiki.example.com.log main;
}
</programlisting>
    <para>
      Reload your nginx config and you should be all set.
    </para>
  </sect2>
  <sect2 id="proxying-to-httpmysite.comwiki">
    <title>Proxying to <literal>http://mysite.com/wiki</literal></title>
    <para>
      Make sure the <literal>mod_proxy</literal>,
      <literal>mod_headers</literal>, <literal>mod_proxy_http</literal>,
      and <literal>mod_proxy_html</literal> modules are loaded.
      <literal>mod_proxy_html</literal> is an external module, which can
      be obtained <ulink url="http://www.haskell.org/ghc/">here</ulink>
      (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 <literal>/wiki/</literal>.
    </para>
    <para>
      First, tell gitit not to compress pages, since
      <literal>mod_proxy_html</literal> needs uncompressed pages to
      parse. You can do this by setting the gitit configuration option
    </para>
    <programlisting>
compress-responses: no
</programlisting>
    <para>
      Second, modify the link in the
      <literal>reset-password-message</literal> in the configuration
      file: instead of
    </para>
    <programlisting>
http://$hostname$:$port$$resetlink$
</programlisting>
    <para>
      set it to
    </para>
    <programlisting>
http://$hostname$/wiki$resetlink$
</programlisting>
    <para>
      Restart gitit.
    </para>
    <para>
      Now add the following lines to the apache configuration file for
      the <literal>mysite.com</literal> server:
    </para>
    <programlisting>
# These commands will proxy /wiki/ to port 5001

ProxyRequests Off

&lt;Proxy *&gt;
  Order deny,allow
  Allow from all
&lt;/Proxy&gt;

ProxyPass /wiki/ http://127.0.0.1:5001/

&lt;Location /wiki/&gt;
  SetOutputFilter  proxy-html
  ProxyPassReverse /
  ProxyHTMLURLMap  /   /wiki/
  ProxyHTMLDocType &quot;&lt;!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'&gt;&quot; XHTML
  RequestHeader unset Accept-Encoding
&lt;/Location&gt;
</programlisting>
    <para>
      Reload your apache configuration and you should be set.
    </para>
    <para>
      For further information on the use of
      <literal>mod_proxy_http</literal> to rewrite URLs, see the
      <ulink url="http://apache.webthing.com/mod_proxy_html/guide.html"><literal>mod_proxy_html</literal>
      guide</ulink>.
    </para>
  </sect2>
</sect1>
<sect1 id="using-gitit-as-a-library">
  <title>Using gitit as a library</title>
  <para>
    By importing the module <literal>Network.Gitit</literal>, you can
    include a gitit wiki (or several of them) in another happstack
    application. There are some simple examples in the haddock
    documentation for <literal>Network.Gitit</literal>.
  </para>
</sect1>
<sect1 id="reporting-bugs">
  <title>Reporting bugs</title>
  <para>
    Bugs may be reported (and feature requests filed) at
    <ulink url="http://code.google.com/p/gitit/issues/list">http://code.google.com/p/gitit/issues/list</ulink>.
  </para>
  <para>
    There is a mailing list for users and developers at
    <ulink url="http://groups.google.com/group/gitit-discuss">http://groups.google.com/group/gitit-discuss</ulink>.
  </para>
</sect1>
<sect1 id="acknowledgements">
  <title>Acknowledgements</title>
  <para>
    A number of people have contributed patches:
  </para>
  <itemizedlist spacing="compact">
    <listitem>
      <para>
        Gwern Branwen helped to optimize gitit and wrote the
        InterwikiPlugin. He also helped with the Feed module.
      </para>
    </listitem>
    <listitem>
      <para>
        Simon Michael contributed the patch adding RST support.
      </para>
    </listitem>
    <listitem>
      <para>
        Henry Laxen added support for password resets and helped with
        the apache proxy instructions.
      </para>
    </listitem>
    <listitem>
      <para>
        Anton van Straaten made the process of page generation more
        modular by adding Gitit.ContentTransformer.
      </para>
    </listitem>
    <listitem>
      <para>
        Robin Green helped improve the plugin API and interface, and
        fixed a security problem with the reset password code.
      </para>
    </listitem>
    <listitem>
      <para>
        Thomas Hartman helped improve the index page, making directory
        browsing persistent, and fixed a bug in template recompilation.
      </para>
    </listitem>
    <listitem>
      <para>
        Justin Bogner improved the appearance of the preview button.
      </para>
    </listitem>
    <listitem>
      <para>
        Kohei Ozaki contributed the ImgTexPlugin.
      </para>
    </listitem>
    <listitem>
      <para>
        Michael Terepeta improved validation of change descriptions.
      </para>
    </listitem>
    <listitem>
      <para>
        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.
      </para>
    </listitem>
  </itemizedlist>
  <para>
    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.
  </para>
  <para>
    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 <literal>img/icons</literal> come from bluetrip as
    well.
  </para>
</sect1>