Gitit User's Guide.page 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583
  1. Gitit
  2. =====
  3. Gitit is a wiki program written in Haskell. It uses [Happstack][] for
  4. the web server and [pandoc][] for markup processing. Pages and uploaded
  5. files are stored in a [git][], [darcs][], or [mercurial][] repository
  6. and may be modified either by using the VCS's command-line tools or
  7. through the wiki's web interface. By default, pandoc's extended version
  8. of markdown is used as a markup language, but reStructuredText, LaTeX,
  9. or HTML can also be used. Pages can be exported in a number of different
  10. formats, including LaTeX, RTF, OpenOffice ODT, and MediaWiki markup.
  11. Gitit can be configured to display TeX math (using [texmath][]) and
  12. highlighted source code (using [highlighting-kate][]).
  13. Other features include
  14. * plugins: dynamically loaded page transformations written in Haskell
  15. (see "Network.Gitit.Interface")
  16. * categories
  17. * TeX math
  18. * syntax highlighting of source code files and code snippets (using
  19. highlighting-kate)
  20. * caching
  21. * Atom feeds (site-wide and per-page)
  22. * a library, "Network.Gitit", that makes it simple to include a gitit
  23. wiki in any happstack application
  24. You can see a running demo at <http://gitit.johnmacfarlane.net>.
  25. [git]: http://git.or.cz
  26. [darcs]: http://darcs.net
  27. [mercurial]: http://mercurial.selenic.com/
  28. [pandoc]: http://johnmacfarlane.net/pandoc
  29. [Happstack]: http://happstack.com
  30. [highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/
  31. [texmath]: http://github.com/jgm/texmath/tree/master
  32. Getting started
  33. ===============
  34. Compiling and installing gitit
  35. ------------------------------
  36. You'll need the [GHC][] compiler and the [cabal-install][] tool. GHC can
  37. be downloaded [here][]. Note that, starting with release 0.5, GHC 6.10
  38. or higher is required. For [cabal-install][] on *nix, follow the [quick
  39. install][] instructions.
  40. [GHC]: http://www.haskell.org/ghc/
  41. [here]: http://www.haskell.org/ghc/
  42. [cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
  43. [quick install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick Installation on Unix
  44. Once you've got cabal-install, installing gitit is trivial:
  45. cabal update
  46. cabal install gitit
  47. These commands will install the latest released version of gitit.
  48. To install a version of gitit checked out from the repository,
  49. change to the gitit directory and type:
  50. cabal install
  51. The `cabal` tool will automatically install all of the required haskell
  52. libraries. If all goes well, by the end of this process, the latest
  53. release of gitit will be installed in your local `.cabal` directory. You
  54. can check this by trying:
  55. gitit --version
  56. If that doesn't work, check to see that `gitit` is in your local
  57. cabal-install executable directory (usually `~/.cabal/bin`). And make
  58. sure `~/.cabal/bin` is in your system path.
  59. Optional syntax highlighting support
  60. ------------------------------------
  61. If pandoc was compiled with optional syntax highlighting support,
  62. this will be available in gitit too. This feature is recommended
  63. if you plan to display source code on your wiki.
  64. Highlighting support requires the [pcre][] library, so make sure that
  65. is installed before continuing.
  66. [pcre]: http://www.pcre.org/
  67. To install gitit with highlighting support, first ensure that pandoc
  68. is compiled with highlighting support, then install gitit as above:
  69. cabal install pandoc -fhighlighting --reinstall
  70. cabal install gitit
  71. Running gitit
  72. -------------
  73. To run gitit, you'll need `git` in your system path. (Or `darcs` or
  74. `hg`, if you're using darcs or mercurial to store the wiki data.)
  75. Gitit assumes that the page files (stored in the git repository) are
  76. encoded as UTF-8. Even page names may be UTF-8 if the file system
  77. supports this. So you should make sure that you are using a UTF-8 locale
  78. when running gitit. (To check this, type `locale`.)
  79. Switch to the directory where you want to run gitit. This should be a
  80. directory where you have write access, since three directories, `static`,
  81. `templates`, and `wikidata`, and two files, `gitit-users` and `gitit.log`,
  82. will be created here. To start gitit, just type:
  83. gitit
  84. If all goes well, gitit will do the following:
  85. 1. Create a git repository, `wikidata`, and add a default front page.
  86. 2. Create a `static` directory containing files to be treated as
  87. static files by gitit.
  88. 3. Create a `templates` directory containing HStringTemplate templates
  89. for wiki pages.
  90. 4. Start a web server on port 5001.
  91. Check that it worked: open a web browser and go to
  92. <http://localhost:5001>.
  93. You can control the port that gitit runs on using the `-p` option:
  94. `gitit -p 4000` will start gitit on port 4000. Additional runtime
  95. options are described by `gitit -h`.
  96. Using gitit
  97. ===========
  98. Wiki links and formatting
  99. -------------------------
  100. For instructions on editing pages and creating links, see the "Help" page.
  101. Gitit interprets links with empty URLs as wikilinks. Thus, in markdown
  102. pages, `[Front Page]()` creates an internal wikilink to the page `Front
  103. Page`. In reStructuredText pages, `` `Front Page <>`_ `` has the same
  104. effect.
  105. If you want to link to a directory listing for a subdirectory, use a
  106. trailing slash: `[foo/bar/]()` creates a link to the directory for
  107. `foo/bar`.
  108. Page metadata
  109. -------------
  110. Pages may optionally begin with a metadata block. Here is an example:
  111. ---
  112. format: latex+lhs
  113. categories: haskell math
  114. toc: no
  115. title: Haskell and
  116. Category Theory
  117. ...
  118. \section{Why Category Theory?}
  119. The metadata block consists of a list of key-value pairs, each on a
  120. separate line. If needed, the value can be continued on one or more
  121. additional line, which must begin with a space. (This is illustrated by
  122. the "title" example above.) The metadata block must begin with a line
  123. `---` and end with a line `...` optionally followed by one or more blank
  124. lines. (The metadata block is a valid YAML document, though not all YAML
  125. documents will be valid metadata blocks.)
  126. Currently the following keys are supported:
  127. format
  128. : Overrides the default page type as specified in the configuration file.
  129. Possible values are `markdown`, `rst`, `latex`, `html`, `markdown+lhs`,
  130. `rst+lhs`, `latex+lhs`. (Capitalization is ignored, so you can also
  131. use `LaTeX`, `HTML`, etc.) The `+lhs` variants indicate that the page
  132. is to be interpreted as literate Haskell. If this field is missing,
  133. the default page type will be used.
  134. categories
  135. : A space or comma separated list of categories to which the page belongs.
  136. toc
  137. : Overrides default setting for table-of-contents in the configuration file.
  138. Values can be `yes`, `no`, `true`, or `false` (capitalization is ignored).
  139. title
  140. : By default the displayed page title is the page name. This metadata element
  141. overrides that default.
  142. Highlighted source code
  143. -----------------------
  144. If gitit was compiled against a version of pandoc that has highlighting
  145. support (see above), you can get highlighted source code by using
  146. [delimited code blocks][]:
  147. ~~~ {.haskell .numberLines}
  148. qsort [] = []
  149. qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
  150. qsort (filter (>= x) xs)
  151. ~~~
  152. To see what languages your pandoc was compiled to highlight:
  153. pandoc -v
  154. [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
  155. Configuring and customizing gitit
  156. =================================
  157. Configuration options
  158. ---------------------
  159. Use the option `-f [filename]` to specify a configuration file:
  160. gitit -f my.conf
  161. If this option is not used, gitit will use a default configuration.
  162. To get a copy of the default configuration file, which you
  163. can customize, just type:
  164. gitit --print-default-config > my.conf
  165. The default configuration file is documented with comments throughout.
  166. The `static` directory
  167. ----------------------
  168. On receiving a request, gitit always looks first in the `static`
  169. directory (or in whatever directory is specified for `static-dir` in
  170. the configuration file). If a file corresponding to the request is
  171. found there, it is served immediately. If the file is not found in
  172. `static`, gitit next looks in the `static` subdirectory of gitit's data
  173. file (`$CABALDIR/share/gitit-x.y.z/data`). This is where default css,
  174. images, and javascripts are stored. If the file is not found there
  175. either, gitit treats the request as a request for a wiki page or wiki
  176. command.
  177. So, you can throw anything you want to be served statically (for
  178. example, a `robots.txt` file or `favicon.ico`) in the `static`
  179. directory. You can override any of gitit's default css, javascript, or
  180. image files by putting a file with the same relative path in `static`.
  181. Note that gitit has a default `robots.txt` file that excludes all
  182. URLs beginning with `/_`.
  183. Note: if you set `static-dir` to be a subdirectory of `repository-path`,
  184. and then add the files in the static directory to your repository, you
  185. can ensure that others who clone your wiki repository get these files
  186. as well. It will not be possible to modify these files using the web
  187. interface, but they will be modifiable via git.
  188. Using a VCS other than git
  189. --------------------------
  190. By default, gitit will store wiki pages in a git repository in the
  191. `wikidata` directory. If you'd prefer to use darcs instead of git,
  192. you need to add the following field to the configuration file:
  193. repository-type: Darcs
  194. If you'd prefer to use mercurial, add:
  195. repository-type: Mercurial
  196. This program may be called "darcsit" instead of "gitit" when a darcs
  197. backend is used.
  198. Note: we recommend that you use gitit/darcsit with darcs version
  199. 2.3.0 or greater. If you must use an older version of darcs, then
  200. you need to compile the filestore library without the (default)
  201. maxcount flag, before (re)installing gitit:
  202. cabal install --reinstall filestore -f-maxcount
  203. cabal install --reinstall gitit
  204. Otherwise you will get an error when you attempt to access your
  205. repository.
  206. Changing the theme
  207. ------------------
  208. To change the look of the wiki, you can modify `custom.css` in
  209. `static/css`.
  210. To change the look of printed pages, copy gitit's default `print.css`
  211. to `static/css` and modify it.
  212. The logo picture can be changed by copying a new PNG file to
  213. `static/img/logo.png`. The default logo is 138x155 pixels.
  214. To change the footer, modify `templates/footer.st`.
  215. For more radical changes, you can override any of the default
  216. templates in `$CABALDIR/share/gitit-x.y.z/data/templates` by copying
  217. the file into `templates` and modifying it. The `page.st` template is
  218. the master template; it includes the others. Interpolated variables are
  219. surrounded by `$`s, so `literal $` must be backslash-escaped.
  220. Adding support for math
  221. -----------------------
  222. To write math on a markdown-formatted wiki page, just enclose it
  223. in dollar signs, as in LaTeX:
  224. Here is a formula: $\frac{1}{\sqrt{c^2}}$
  225. You can write display math by enclosing it in double dollar signs:
  226. $$\frac{1}{\sqrt{c^2}}$$
  227. Gitit can display TeX math in three different ways, depending on the
  228. setting of `math` in the configuration file:
  229. 1. `mathml` (default): Math will be converted to MathML using
  230. [texmath][]. This method works with IE+mathplayer, Firefox, and
  231. Opera, but not Safari.
  232. 2. `jsMath`: Math will be rendered using the [jsMath][] javascript.
  233. If you want to use this method, download `jsMath` and `jsMath
  234. Image Fonts` from the [jsMath download page][]. You'll have two
  235. `.zip` archives. Unzip them both in the `static/js` directory (a new
  236. subdirectory, `jsMath`, will be created). This works with all
  237. browsers, but is slower and not as nice looking as MathML.
  238. 3. `raw`: Math will be rendered as raw LaTeX codes.
  239. [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
  240. Restricting access
  241. ------------------
  242. If you want to limit account creation on your wiki, the easiest way to do this
  243. is to provide an `access-question` in your configuration file. (See the commented
  244. default configuration file.) Nobody will be able to create an account without
  245. knowing the answer to the access question.
  246. Another approach is to use HTTP authentication. (See the config file comments on
  247. `authentication-method`.)
  248. Plugins
  249. =======
  250. Plugins are small Haskell programs that transform a wiki page after it
  251. has been converted from Markdown or RST. See the example plugins in the
  252. `plugins` directory. To enable a plugin, include the path to the plugin
  253. (or its module name) in the `plugins` field of the configuration file.
  254. (If the plugin name starts with `Network.Gitit.Plugin.`, gitit will assume that
  255. the plugin is an installed module and will not look for a source file.)
  256. Plugin support is enabled by default. However, plugin support makes
  257. the gitit executable considerably larger and more memory-hungry.
  258. If you don't need plugins, you may want to compile gitit without plugin
  259. support. To do this, unset the `plugins` Cabal flag:
  260. cabal install --reinstall gitit -f-plugins
  261. Note also that if you compile gitit for executable profiling, attempts
  262. to load plugins will result in "internal error: PAP object entered!"
  263. Accessing the wiki through git
  264. ==============================
  265. All the pages and uploaded files are stored in a git repository. By
  266. default, this lives in the `wikidata` directory (though this can be
  267. changed through configuration options). So you can interact with the
  268. wiki using git command line tools:
  269. git clone ssh://my.server.edu/path/of/wiki/wikidata
  270. cd wikidata
  271. vim Front\ Page.page # edit the page
  272. git commit -m "Added message about wiki etiquette" Front\ Page.page
  273. git push
  274. If you now look at the Front Page on the wiki, you should see your changes
  275. reflected there. Note that the pages all have the extension `.page`.
  276. If you are using the darcs or mercurial backend, the commands will
  277. be slightly different. See the documentation for your VCS for
  278. details.
  279. Performance
  280. ===========
  281. Caching
  282. -------
  283. By default, gitit does not cache content. If your wiki receives a lot of
  284. traffic or contains pages that are slow to render, you may want to activate
  285. caching. To do this, set the configuration option `use-cache` to `yes`.
  286. By default, rendered pages, highlighted source files, and exported PDFs
  287. will be cached in the `cache` directory. (Another directory can be
  288. specified by setting the `cache-dir` configuration option.)
  289. Cached pages are updated when pages are modified using the web
  290. interface. They are not updated when pages are modified directly through
  291. git or darcs. However, the cache can be refreshed manually by pressing
  292. Ctrl-R when viewing a page, or by sending an HTTP GET or POST request to
  293. `/_expire/path/to/page`, where `path/to/page` is the name of the page to
  294. be expired.
  295. Users who frequently update pages using git or darcs may wish to add a
  296. hook to the repository that makes the appropriate HTTP request to expire
  297. pages when they are updated. To facilitate such hooks, the gitit cabal
  298. package includes an executable `expireGititCache`. Assuming you are
  299. running gitit at port 5001 on localhost, and the environment variable
  300. `CHANGED_FILES` contains a list of the files that have changed, you can
  301. expire their cached versions using
  302. expireGititCache http://localhost:5001 $CHANGED_FILES
  303. Or you can specify the files directly:
  304. expireGititCache http://localhost:5001 "Front Page.page" foo/bar/baz.c
  305. This program will return a success status (0) if the page has been
  306. successfully expired (or if it was never cached in the first place),
  307. and a failure status (> 0) otherwise.
  308. The cache is persistent through restarts of gitit. To expire all cached
  309. pages, simply remove the `cache` directory.
  310. Idle
  311. ----
  312. By default, GHC's runtime will repeatedly attempt to collect garbage
  313. when an executable like Gitit is idle. This means that gitit will, after
  314. the first page request, never use 0% CPU time and sleep, but will use
  315. ~1%. This can be bad for battery life, among other things.
  316. To fix this, one can disable the idle-time GC with the runtime flag
  317. `-I0`:
  318. gitit -f my.conf +RTS -I0 -RTS
  319. Using gitit with apache
  320. =======================
  321. Most users who run a public-facing gitit will want gitit to appear
  322. at a nice URL like `http://wiki.mysite.com` or
  323. `http://mysite.com/wiki` rather than `http://mysite.com:5001`.
  324. This can be achieved using apache's `mod_proxy`.
  325. Proxying to `http://wiki.mysite.com`
  326. ------------------------------------
  327. Set up your DNS so that `http://wiki.mysite.com` maps to
  328. your server's IP address. Make sure that the `mod_proxy` module is
  329. loaded, and set up a virtual host with the following configuration:
  330. <VirtualHost *>
  331. ServerName wiki.mysite.com
  332. DocumentRoot /var/www/
  333. RewriteEngine On
  334. ProxyPreserveHost On
  335. ProxyRequests Off
  336. <Proxy *>
  337. Order deny,allow
  338. Allow from all
  339. </Proxy>
  340. ProxyPassReverse / http://127.0.0.1:5001
  341. RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
  342. ErrorLog /var/log/apache2/error.log
  343. LogLevel warn
  344. CustomLog /var/log/apache2/access.log combined
  345. ServerSignature On
  346. </VirtualHost>
  347. Reload your apache configuration and you should be all set.
  348. Proxying to `http://mysite.com/wiki`
  349. ------------------------------------
  350. Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
  351. and `mod_proxy_html` modules are loaded. `mod_proxy_html`
  352. is an external module, which can be obtained [here]
  353. (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
  354. occur in web pages. Here we will use it to rewrite gitit's links so that
  355. they all begin with `/wiki/`.
  356. First, tell gitit not to compress pages, since `mod_proxy_html` needs
  357. uncompressed pages to parse. You can do this by setting the gitit
  358. configuration option
  359. compress-responses: no
  360. Second, modify the link in the `reset-password-message` in the
  361. configuration file: instead of
  362. http://$hostname$:$port$$resetlink$
  363. set it to
  364. http://$hostname$/wiki$resetlink$
  365. Restart gitit.
  366. Now add the following lines to the apache configuration file for the
  367. `mysite.com` server:
  368. # These commands will proxy /wiki/ to port 5001
  369. ProxyRequests Off
  370. <Proxy *>
  371. Order deny,allow
  372. Allow from all
  373. </Proxy>
  374. ProxyPass /wiki/ http://127.0.0.1:5001/
  375. <Location /wiki/>
  376. SetOutputFilter proxy-html
  377. ProxyPassReverse /
  378. ProxyHTMLURLMap / /wiki/
  379. RequestHeader unset Accept-Encoding
  380. </Location>
  381. Reload your apache configuration and you should be set.
  382. For further information on the use of `mod_proxy_http` to rewrite URLs,
  383. see the [`mod_proxy_html` guide].
  384. [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
  385. Using gitit as a library
  386. ========================
  387. By importing the module `Network.Gitit`, you can include a gitit wiki
  388. (or several of them) in another happstack application. There are some
  389. simple examples in the haddock documentation for `Network.Gitit`.
  390. Reporting bugs
  391. ==============
  392. Bugs may be reported (and feature requests filed) at
  393. <http://code.google.com/p/gitit/issues/list>.
  394. There is a mailing list for users and developers at
  395. <http://groups.google.com/group/gitit-discuss>.
  396. Acknowledgements
  397. ================
  398. A number of people have contributed patches:
  399. - Gwern Branwen helped to optimize gitit and wrote the
  400. InterwikiPlugin. He also helped with the Feed module.
  401. - Simon Michael contributed the patch adding RST support.
  402. - Henry Laxen added support for password resets and helped with
  403. the apache proxy instructions.
  404. - Anton van Straaten made the process of page generation
  405. more modular by adding Gitit.ContentTransformer.
  406. - Robin Green helped improve the plugin API and interface, and
  407. fixed a security problem with the reset password code.
  408. - Thomas Hartman helped improve the index page, making directory
  409. browsing persistent, and fixed a bug in template recompilation.
  410. - Justin Bogner improved the appearance of the preview button.
  411. - Kohei Ozaki contributed the ImgTexPlugin.
  412. - Michael Terepeta improved validation of change descriptions.
  413. - mightybyte suggested making gitit available as a library,
  414. and contributed a patch to ifLoggedIn that was needed to
  415. make gitit usable with a custom authentication scheme.
  416. I am especially grateful to the darcs team for using darcsit for
  417. their public-facing wiki. This has helped immensely in identifying
  418. issues and improving performance.
  419. Gitit's default visual layout is shamelessly borrowed from Wikipedia.
  420. The stylesheets are influenced by Wikipedia's stylesheets and by the
  421. bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
  422. `img/icons` come from bluetrip as well.