Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 449 lines (327 sloc) 15.802 kB
45a9c7f @jgm Reformatted README using standard markdown.
authored
1 Gitit
2 =====
89725fd @jgm Initial commit.
authored
3
f8ab67e @jgm Reformatting (line lengths) of README.
authored
4 Gitit is a wiki program written in Haskell. It uses [Happstack][]
5 for the web server and [pandoc][] for markup processing. Pages and
6 uploaded files are stored in a [git][] or [darcs][] repository and may
7 be modified either by using the VCS's command-line tools or through the
8 wiki's web interface. By default, pandoc's extended version of markdown
0f4f9c6 @jgm Indicate in README that LaTeX or HTML formats can be used.
authored
9 is used as a markup language, but reStructuredText, LaTeX, or HTML
10 can also be used. Pages can be exported in a number of different
11 formats, including LaTeX, RTF, OpenOffice ODT, and MediaWiki markup.
12 Gitit can be configured to display TeX math (using [jsMath][]) and
13 highlighted source code (using [highlighting-kate][]).
89725fd @jgm Initial commit.
authored
14
15 [git]: http://git.or.cz
d9c8cd8 @jgm Modified description slightly, mentioning darcs as well as git.
authored
16 [darcs]: http://darcs.net
89725fd @jgm Initial commit.
authored
17 [pandoc]: http://johnmacfarlane.net/pandoc
fd9eed5 @jgm Changed mentions of HAppS to Happstack.
authored
18 [Happstack]: http://happstack.com
f8cd051 @jgm Updated README.
authored
19 [jsMath]: http://www.math.union.edu/~dpvc/jsMath/
20 [highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/
89725fd @jgm Initial commit.
authored
21
45a9c7f @jgm Reformatted README using standard markdown.
authored
22 Getting started
23 ===============
89725fd @jgm Initial commit.
authored
24
45a9c7f @jgm Reformatted README using standard markdown.
authored
25 Compiling and installing gitit
26 ------------------------------
89725fd @jgm Initial commit.
authored
27
45a9c7f @jgm Reformatted README using standard markdown.
authored
28 You'll need the [GHC][] compiler and the [cabal-install][] tool. GHC can
98adca8 @jgm Note the GHC 6.10 requirement in README.
authored
29 be downloaded [here][]. Note that, starting with release 0.5, GHC 6.10
30 or higher is required. For [cabal-install][] on *nix, follow the [quick
45a9c7f @jgm Reformatted README using standard markdown.
authored
31 install][] instructions.
89725fd @jgm Initial commit.
authored
32
33 [GHC]: http://www.haskell.org/ghc/
34 [here]: http://www.haskell.org/ghc/
35 [cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
36 [quick install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick Installation on Unix
37
97e0043 Improved README.
John MacFarlane authored
38 Once you've got cabal-install, installing gitit is trivial:
89725fd @jgm Initial commit.
authored
39
a7c11fe @jgm Simplified installation instructions.
authored
40 cabal update
89725fd @jgm Initial commit.
authored
41 cabal install gitit
42
a7c11fe @jgm Simplified installation instructions.
authored
43 These commands will install the latest released version of gitit.
89725fd @jgm Initial commit.
authored
44 To install a version of gitit checked out from the repository,
45 change to the gitit directory and type:
46
47 cabal install
48
49 The `cabal` tool will automatically install all of the required haskell
50 libraries. If all goes well, by the end of this process, the latest
51 release of gitit will be installed in your local `.cabal` directory. You
52 can check this by trying:
53
54 gitit --version
55
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
97e0043 Improved README.
John MacFarlane authored
60 Optional syntax highlighting support
61 ------------------------------------
62
63 If pandoc was compiled with optional syntax highlighting support,
64 this will be available in gitit too. This feature is recommended
65 if you plan to display source code on your wiki.
66
67 Highlighting support requires the [pcre][] library, so make sure that
68 is installed before continuing.
69
70 [pcre]: http://www.pcre.org/
71
72 To install gitit with highlighting support, first ensure that pandoc
73 is compiled with highlighting support, then install gitit as above:
74
75 cabal install pandoc -fhighlighting --reinstall
76 cabal install gitit
77
1f07157 @jgm Slightly improved plugins documentation.
authored
78 Optional plugins support
79 ------------------------
80
f8ab67e @jgm Reformatting (line lengths) of README.
authored
81 Plugins are small Haskell programs that transform a wiki page after it
82 has been converted from Markdown or RST. See the example plugins in the
83 `plugins` directory. To enable a plugin, include the path to the plugin
84 (or its module name) in the `plugins` field of the configuration file.
3da0cc8 @jgm Fixed plugins to use new Network.Gitit prefix.
authored
85 (If the plugin name starts with `Network.Gitit.Plugin.`, gitit will assume that
f8ab67e @jgm Reformatting (line lengths) of README.
authored
86 the plugin is an installed module and will not look for a source file.)
1f07157 @jgm Slightly improved plugins documentation.
authored
87
88 The gitit executable will be much larger if plugins support is compiled
89 in. Plugin support is disabled by default. To enable support for
90 plugins, pass the `plugins` flag to Cabal:
91
92 cabal install gitit -fplugins
93
94 Note also that if you compile gitit for executable profiling, attempts
95 to load plugins will result in "internal error: PAP object entered!"
96
45a9c7f @jgm Reformatted README using standard markdown.
authored
97 Running gitit
98 -------------
89725fd @jgm Initial commit.
authored
99
97e0043 Improved README.
John MacFarlane authored
100 To run gitit, you'll need [git][] in your system path. (Or
101 [darcs][], if you're using darcs to store the wiki data.)
89725fd @jgm Initial commit.
authored
102
97e0043 Improved README.
John MacFarlane authored
103 Gitit assumes that the page files (stored in the git repository) are
104 encoded as UTF-8. Even page names may be UTF-8 if the file system
105 supports this. So you should make sure that you are using a UTF-8 locale
106 when running gitit. (To check this, type `locale`.)
73db5a1 @jgm Noted need for UTF-8 locale in README.
authored
107
f8ab67e @jgm Reformatting (line lengths) of README.
authored
108 Switch to the directory where you want to run gitit. This should be a
109 directory where you have write access, since two directories, `static`
110 and `wikidata`, and two files, `gitit-users` and `template.html`, will
111 be created here. To start gitit, just type:
89725fd @jgm Initial commit.
authored
112
113 gitit
114
115 If all goes well, gitit will do the following:
116
117 1. Create a git repository, `wikidata`, and add a default front page.
97e0043 Improved README.
John MacFarlane authored
118 2. Create a `static` directory containing the scripts, images,
119 and stylesheets used by gitit.
120 3. Create a `template.html` file containing an HStringTemplate template
f498fc6 @jgm Use HStringTemplate template for pages.
authored
121 for wiki pages.
122 4. Start a web server on port 5001.
89725fd @jgm Initial commit.
authored
123
f8ab67e @jgm Reformatting (line lengths) of README.
authored
124 Check that it worked: open a web browser and go to
125 <http://localhost:5001>.
97e0043 Improved README.
John MacFarlane authored
126
7fa7383 @jgm Updated README with information about metadata block.
authored
127 Using gitit
128 ===========
129
97e0043 Improved README.
John MacFarlane authored
130 Wiki links and formatting
131 -------------------------
132
133 For instructions on editing pages and creating links, see the "Help" page.
134
f8ab67e @jgm Reformatting (line lengths) of README.
authored
135 Gitit interprets links with empty URLs as wikilinks. Thus, in markdown
136 pages, `[Front Page]()` creates an internal wikilink to the page `Front
137 Page`. In reStructuredText pages, `` `Front Page <>`_ `` has the same
138 effect.
89725fd @jgm Initial commit.
authored
139
c332b94 @jgm Documentation changes for new index link format.
authored
140 If you want to link to a directory listing for a subdirectory, use a
141 trailing slash: `[foo/bar/]()` creates a link to the directory for
142 `foo/bar`.
143
7fa7383 @jgm Updated README with information about metadata block.
authored
144 Page metadata
145 -------------
146
147 Pages may optionally begin with a metadata block. Here is an example:
148
38209d9 @jgm Updated README with new metadata format.
authored
149 ---
150 format: latex+lhs
151 categories: haskell math
152 toc: no
153 title: Haskell and
7fa7383 @jgm Updated README with information about metadata block.
authored
154 Category Theory
38209d9 @jgm Updated README with new metadata format.
authored
155 ...
7fa7383 @jgm Updated README with information about metadata block.
authored
156
157 \section{Why Category Theory?}
158
159 The metadata block consists of a list of key-value pairs, each on a separate
160 line. If needed, the value can be continued on one or more additional
161 line, which must begin with a space. (This is illustrated by the "title"
38209d9 @jgm Updated README with new metadata format.
authored
162 example above.) The metadata block must begin with a line `---` and end with
163 a line `...` followed by one or more blank lines. (The metadata block is a
164 valid YAML document, though not all YAML documents will be valid metadata
165 blocks.)
7fa7383 @jgm Updated README with information about metadata block.
authored
166
167 Currently the following keys are supported:
168
169 format
170 : Overrides the default page type as specified in the configuration file.
171 Possible values are `markdown`, `rst`, `latex`, `html`, `markdown+lhs`,
172 `rst+lhs`, `latex+lhs`. (Capitalization is ignored, so you can also
173 use `LaTeX`, `HTML`, etc.) The `+lhs` variants indicate that the page
174 is to be interpreted as literate Haskell. If this field is missing,
175 the default page type will be used.
176
177 categories
178 : A space or comma separated list of categories to which the page belongs.
179
180 toc
181 : Overrides default setting for table-of-contents in the configuration file.
182 Values can be `yes`, `no`, `true`, or `false` (capitalization is ignored).
183
184 title
185 : By default the displayed page title is the page name. This metadata element
186 overrides that default.
187
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
188 Configuring gitit
189 =================
190
45a9c7f @jgm Reformatted README using standard markdown.
authored
191 Configuration options
192 ---------------------
89725fd @jgm Initial commit.
authored
193
194 You can set some configuration options when starting gitit, using the
ce07825 @jgm Added data/default.conf, which defines default config file values.
authored
195 option `-f [filename]`. To get a copy of the default configuration file,
196 which you can customize, just type:
197
198 gitit --print-default-config > default.conf
199
200 The default configuration file is documented with comments throughout.
2859d1b @jgm Document --print-default-config.
authored
201
45a9c7f @jgm Reformatted README using standard markdown.
authored
202 The `static` directory
203 ----------------------
89725fd @jgm Initial commit.
authored
204
f8ab67e @jgm Reformatting (line lengths) of README.
authored
205 If there is no wiki page or uploaded file corresponding to a request,
206 gitit always looks last in the `static` directory. So, for example,
207 a file `foo.jpg` in the `img` subdirectory of the `static` directory
208 will be accessible at the url `/img/foo.jpg`. Pandoc creates three
209 subdirectories of `static`, `css`, `img`, and `js`, which include the
210 icons, stylesheets, and javascripts it uses.
89725fd @jgm Initial commit.
authored
211
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
212 Note: if you set `static-dir` to be a subdirectory of `repository-path`,
89e0a04 @jgm Added note about possibility of putting static inside repository.
authored
213 and then add the files in the static directory to your repository, you
214 can ensure that others who clone your wiki repository get these files
215 as well. It will not be possible to modify these files using the web
216 interface, but they will be modifiable via git.
217
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
218 Using darcs instead of git
219 --------------------------
220
221 By default, gitit will store wiki pages in a git repository in the
222 `wikidata` directory. If you'd prefer to use darcs instead of git,
223 you need to add the following field to the configuration file:
224
225 repository-type: Darcs
226
227 This program may be called "darcsit" instead of "gitit" when a darcs
228 backend is used.
229
45a9c7f @jgm Reformatted README using standard markdown.
authored
230 Changing the theme
231 ------------------
89725fd @jgm Initial commit.
authored
232
97e0043 Improved README.
John MacFarlane authored
233 To change the look of the wiki, you can modify `screen.css` in
234 `static/css`. But a better approach is to add a line to `template.html`
235 that imports your own custom stylesheet. This line should go
236 after the line that links to `/css/screen.css`:
237
238 <link href="/css/my-screen.css" rel="stylesheet" media="screen, projection" type="text/css" />
239
240 Then add `my-screen.css` to the `static/css` directory and customize
241 it as you see fit. The advantage of this approach is that you won't
242 need to merge changes in `screen.css` when gitit is updated. You can
243 just copy the revised `screen.css` into your `static/css` directory.
244
5c5c337 @jgm Updated README.
authored
245 To change the look of printed pages, modify `print.css`.
97e0043 Improved README.
John MacFarlane authored
246
f498fc6 @jgm Use HStringTemplate template for pages.
authored
247 The logo picture can be changed by copying a new PNG file to
97e0043 Improved README.
John MacFarlane authored
248 `static/img/logo.png`.
249
250 For more radical changes, you can modify `template.html`.
251 Note that interpolated variables are surrounded by `$`s, so literal
252 `$` must be backslash-escaped.
89725fd @jgm Initial commit.
authored
253
45a9c7f @jgm Reformatted README using standard markdown.
authored
254 Adding support for math
255 -----------------------
89725fd @jgm Initial commit.
authored
256
f8ab67e @jgm Reformatting (line lengths) of README.
authored
257 Gitit is designed to work with [jsMath][] to display LaTeX math in
258 HTML. Download `jsMath` and `jsMath Image Fonts` from the [jsMath
259 download page][]. You'll have two `.zip` archives. Unzip them both
260 in the `static/js` directory (a new subdirectory, `jsMath`, will be
261 created). You can test to see if math is working properly by clicking
262 "help" on the top navigation bar and looking for the math example (the
263 quadratic formula). Note that if you copied the `jsMath` directory into
264 `static` *after* starting gitit, you will have to restart gitit for the
265 change to be noticed. Gitit checks for the existence of the jsMath files
266 when it starts, and will not include links to them unless they exist.
89725fd @jgm Initial commit.
authored
267
7fa7383 @jgm Updated README with information about metadata block.
authored
268 To write math on a markdown-formatted wiki page, just enclose it
269 in dollar signs, as in LaTeX:
89725fd @jgm Initial commit.
authored
270
271 Here is a formula: $\frac{1}{\sqrt{c^2}}$
272
273 You can write display math by enclosing it in double dollar signs:
274
275 $$\frac{1}{\sqrt{c^2}}$$
276
277 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
278
45a9c7f @jgm Reformatted README using standard markdown.
authored
279 Highlighted source code
280 -----------------------
89725fd @jgm Initial commit.
authored
281
f8ab67e @jgm Reformatting (line lengths) of README.
authored
282 If gitit was compiled against a version of pandoc that has highlighting
283 support (see above), you can get highlighted source code by using
284 [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
285
286 ~~~ {.haskell .numberLines}
287 qsort [] = []
288 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
289 qsort (filter (>= x) xs)
290 ~~~
291
292 To see what languages are available:
293
294 pandoc -v
295
296 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
297
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
298 Accessing the wiki via git or darcs
299 ===================================
89725fd @jgm Initial commit.
authored
300
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
301 All the pages and uploaded files are stored in a git or darcs
302 repository. By default, this lives in the `wikidata` directory (though
303 this can be changed through configuration options). So you can interact
304 with the wiki using git command line tools:
89725fd @jgm Initial commit.
authored
305
306 git clone ssh://my.server.edu/path/of/wiki/wikidata
307 cd wikidata
308 vim Front\ Page.page # edit the page
309 git commit -m "Added message about wiki etiquette" Front\ Page.page
310 git push
311
312 If you now look at the Front Page on the wiki, you should see your changes
313 reflected there. Note that the pages all have the extension `.page`.
314
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
315 Using gitit with apache
316 =======================
317
318 Most users who run a public-facing gitit will want gitit to appear
319 at a nice URL like `http://wiki.mysite.com` or
320 `http://mysite.com/wiki` rather than `http://mysite.com:5001`.
321 This can be achieved using apache's `mod_proxy`.
322
323 Proxying to `http://wiki.mysite.com`
324 ------------------------------------
325
326 Set up your DNS so that `http://wiki.mysite.com` maps to
327 your server's IP address. Make sure that the `mod_proxy` module is
328 loaded, and set up a virtual host with the following configuration:
329
330 <VirtualHost *>
331 ServerName wiki.mysite.com
332 DocumentRoot /var/www/
333 RewriteEngine On
334 ProxyPreserveHost On
335 ProxyRequests Off
336
337 <Proxy *>
338 Order deny,allow
339 Allow from all
340 </Proxy>
341
342 ProxyPassReverse / http://127.0.0.1:5001
343 RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
344
345 ErrorLog /var/log/apache2/error.log
346 LogLevel warn
347
348 CustomLog /var/log/apache2/access.log combined
349 ServerSignature On
350
351 </VirtualHost>
352
353 Reload your apache configuration and you should be all set.
354
355 Proxying to `http://mysite.com/wiki`
356 ------------------------------------
357
358 Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
359 and `mod_proxy_html` modules are loaded. `mod_proxy_html`
360 is an external module, which can be obtained [here]
361 (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
362 occur in web pages. Here we will use it to rewrite gitit's links so that
363 they all begin with `/wiki/`.
364
f8ab67e @jgm Reformatting (line lengths) of README.
authored
365 First, tell gitit not to compress pages, since `mod_proxy_html` needs
366 uncompressed pages to parse. You can do this by setting the gitit
367 configuration option
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
368
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
369 compress-responses: no
370
371 Second, modify the link in the `reset-password-message` in the
372 configuration file: instead of
373
374 http://$hostname$:$port$$resetlink$
375
376 set it to
377
378 http://$hostname$/wiki$resetlink$
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
379
380 Restart gitit.
381
382 Now add the following lines to the apache configuration file for the
383 `mysite.com` server:
384
385 # These commands will proxy /wiki/ to port 5001
386
387 ProxyRequests Off
388
389 <Proxy *>
390 Order deny,allow
391 Allow from all
392 </Proxy>
393
394 ProxyPass /wiki/ http://127.0.0.1:5001/
395
396 <Location /wiki/>
397 SetOutputFilter proxy-html
398 ProxyPassReverse /
399 ProxyHTMLURLMap / /wiki/
400 RequestHeader unset Accept-Encoding
401 </Location>
402
403 Reload your apache configuration and you should be set.
404
405 For further information on the use of `mod_proxy_http` to rewrite URLs,
406 see the [`mod_proxy_html` guide].
407
408 [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
409
e86d3dc @jgm Added note on using gitit as a library to README.
authored
410 Using gitit as a library
411 ========================
412
413 By importing the module `Network.Gitit`, you can include a gitit wiki
414 (or several of them) in another happstack application. There are some
415 simple examples in the haddock documentation for `Network.Gitit`.
416
45a9c7f @jgm Reformatted README using standard markdown.
authored
417 Reporting bugs
418 ==============
89725fd @jgm Initial commit.
authored
419
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
420 Bugs may be reported (and feature requests filed) at
421 <http://code.google.com/p/gitit/issues/list>.
89725fd @jgm Initial commit.
authored
422
45a9c7f @jgm Reformatted README using standard markdown.
authored
423 Acknowledgements
424 ================
89725fd @jgm Initial commit.
authored
425
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
426 A number of people have contributed patches:
427
8500b29 @jgm More contributors.
authored
428 - Gwern Branwen helped to optimize gitit and wrote the
429 InterwikiPlugin.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
430 - Simon Michael contributed the patch adding RST support.
431 - Henry Laxen added support for password resets and helped with
432 the apache proxy instructions.
433 - Anton van Straaten made the process of page generation
434 more modular by adding Gitit.ContentTransformer.
435 - Robin Green helped improve the plugin API and interface.
edeca79 More acknowledgements.
John MacFarlane authored
436 - Thomas Hartman helped improve the index page, making directory
437 browsing persistent.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
438 - Justin Bogner improved the appearance of the preview button.
8500b29 @jgm More contributors.
authored
439 - Kohei Ozaki contributed the ImgTexPlugin.
cf6e15e @jgm Added acknowledgement for mightybyte.
authored
440 - mightybyte suggested making gitit available as a library,
441 and contributed a patch to ifLoggedIn that was needed to
442 make gitit usable with a custom authentication scheme.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
443
444 Gitit's default visual layout is shamelessly borrowed from Wikipedia.
5c5c337 @jgm Updated README.
authored
445 The stylesheets are influenced by Wikipedia's stylesheets and by the
446 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
447 `img/icons` come from bluetrip as well.
448
Something went wrong with that request. Please try again.