Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 454 lines (331 sloc) 16.06 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
f1f023a @jgm Use nested templates in templates/ directory rather than template.html.
authored
109 directory where you have write access, since three directories, `static`,
110 `templates`, and `wikidata`, and two files, `gitit-users` and `gitit.log`,
111 will 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.
f1f023a @jgm Use nested templates in templates/ directory rather than template.html.
authored
120 3. Create a `templates` directory containing HStringTemplate templates
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 options...
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 options...
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
f1f023a @jgm Use nested templates in templates/ directory rather than template.html.
authored
234 `static/css`. But a better approach is to add a line to
235 `templates/page.st` that imports your own custom stylesheet. This line
236 should go after the line that links to `/css/screen.css`:
97e0043 Improved README.
John MacFarlane authored
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
f1f023a @jgm Use nested templates in templates/ directory rather than template.html.
authored
250 For more radical changes, you can modify any of the templates in
251 `templates`. The `page.st` template is the master template; it includes
252 the others. Interpolated variables are surrounded by `$`s, so
253 `literal $` must be backslash-escaped.
89725fd @jgm Initial commit.
authored
254
45a9c7f @jgm Reformatted README using standard markdown.
authored
255 Adding support for math
256 -----------------------
89725fd @jgm Initial commit.
authored
257
f8ab67e @jgm Reformatting (line lengths) of README.
authored
258 Gitit is designed to work with [jsMath][] to display LaTeX math in
259 HTML. Download `jsMath` and `jsMath Image Fonts` from the [jsMath
260 download page][]. You'll have two `.zip` archives. Unzip them both
261 in the `static/js` directory (a new subdirectory, `jsMath`, will be
262 created). You can test to see if math is working properly by clicking
263 "help" on the top navigation bar and looking for the math example (the
264 quadratic formula). Note that if you copied the `jsMath` directory into
265 `static` *after* starting gitit, you will have to restart gitit for the
266 change to be noticed. Gitit checks for the existence of the jsMath files
267 when it starts, and will not include links to them unless they exist.
89725fd @jgm Initial commit.
authored
268
7fa7383 @jgm Updated README with information about metadata block.
authored
269 To write math on a markdown-formatted wiki page, just enclose it
270 in dollar signs, as in LaTeX:
89725fd @jgm Initial commit.
authored
271
272 Here is a formula: $\frac{1}{\sqrt{c^2}}$
273
274 You can write display math by enclosing it in double dollar signs:
275
276 $$\frac{1}{\sqrt{c^2}}$$
277
278 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
279
45a9c7f @jgm Reformatted README using standard markdown.
authored
280 Highlighted source code
281 -----------------------
89725fd @jgm Initial commit.
authored
282
f8ab67e @jgm Reformatting (line lengths) of README.
authored
283 If gitit was compiled against a version of pandoc that has highlighting
284 support (see above), you can get highlighted source code by using
285 [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
286
287 ~~~ {.haskell .numberLines}
288 qsort [] = []
289 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
290 qsort (filter (>= x) xs)
291 ~~~
292
293 To see what languages are available:
294
295 pandoc -v
296
297 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
298
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
299 Accessing the wiki via git or darcs
300 ===================================
89725fd @jgm Initial commit.
authored
301
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
302 All the pages and uploaded files are stored in a git or darcs
303 repository. By default, this lives in the `wikidata` directory (though
304 this can be changed through configuration options). So you can interact
305 with the wiki using git command line tools:
89725fd @jgm Initial commit.
authored
306
307 git clone ssh://my.server.edu/path/of/wiki/wikidata
308 cd wikidata
309 vim Front\ Page.page # edit the page
310 git commit -m "Added message about wiki etiquette" Front\ Page.page
311 git push
312
313 If you now look at the Front Page on the wiki, you should see your changes
314 reflected there. Note that the pages all have the extension `.page`.
315
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
316 Using gitit with apache
317 =======================
318
319 Most users who run a public-facing gitit will want gitit to appear
320 at a nice URL like `http://wiki.mysite.com` or
321 `http://mysite.com/wiki` rather than `http://mysite.com:5001`.
322 This can be achieved using apache's `mod_proxy`.
323
324 Proxying to `http://wiki.mysite.com`
325 ------------------------------------
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
331 <VirtualHost *>
332 ServerName wiki.mysite.com
333 DocumentRoot /var/www/
334 RewriteEngine On
335 ProxyPreserveHost On
336 ProxyRequests Off
337
338 <Proxy *>
339 Order deny,allow
340 Allow from all
341 </Proxy>
342
343 ProxyPassReverse / http://127.0.0.1:5001
344 RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
345
346 ErrorLog /var/log/apache2/error.log
347 LogLevel warn
348
349 CustomLog /var/log/apache2/access.log combined
350 ServerSignature On
351
352 </VirtualHost>
353
354 Reload your apache configuration and you should be all set.
355
356 Proxying to `http://mysite.com/wiki`
357 ------------------------------------
358
359 Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
360 and `mod_proxy_html` modules are loaded. `mod_proxy_html`
361 is an external module, which can be obtained [here]
362 (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
363 occur in web pages. Here we will use it to rewrite gitit's links so that
364 they all begin with `/wiki/`.
365
f8ab67e @jgm Reformatting (line lengths) of README.
authored
366 First, tell gitit not to compress pages, since `mod_proxy_html` needs
367 uncompressed pages to parse. You can do this by setting the gitit
368 configuration option
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
369
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
370 compress-responses: no
371
372 Second, modify the link in the `reset-password-message` in the
373 configuration file: instead of
374
375 http://$hostname$:$port$$resetlink$
376
377 set it to
378
379 http://$hostname$/wiki$resetlink$
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
380
381 Restart gitit.
382
383 Now add the following lines to the apache configuration file for the
384 `mysite.com` server:
385
386 # These commands will proxy /wiki/ to port 5001
387
388 ProxyRequests Off
389
390 <Proxy *>
391 Order deny,allow
392 Allow from all
393 </Proxy>
394
395 ProxyPass /wiki/ http://127.0.0.1:5001/
396
397 <Location /wiki/>
398 SetOutputFilter proxy-html
399 ProxyPassReverse /
400 ProxyHTMLURLMap / /wiki/
401 RequestHeader unset Accept-Encoding
402 </Location>
403
404 Reload your apache configuration and you should be set.
405
406 For further information on the use of `mod_proxy_http` to rewrite URLs,
407 see the [`mod_proxy_html` guide].
408
409 [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
410
e86d3dc @jgm Added note on using gitit as a library to README.
authored
411 Using gitit as a library
412 ========================
413
414 By importing the module `Network.Gitit`, you can include a gitit wiki
415 (or several of them) in another happstack application. There are some
416 simple examples in the haddock documentation for `Network.Gitit`.
417
45a9c7f @jgm Reformatted README using standard markdown.
authored
418 Reporting bugs
419 ==============
89725fd @jgm Initial commit.
authored
420
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
421 Bugs may be reported (and feature requests filed) at
422 <http://code.google.com/p/gitit/issues/list>.
89725fd @jgm Initial commit.
authored
423
41595ee @jgm Added notice of mailing list to README.
authored
424 There is a mailing list for users and developers at
425 <http://groups.google.com/group/gitit-discuss>.
426
45a9c7f @jgm Reformatted README using standard markdown.
authored
427 Acknowledgements
428 ================
89725fd @jgm Initial commit.
authored
429
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
430 A number of people have contributed patches:
431
8500b29 @jgm More contributors.
authored
432 - Gwern Branwen helped to optimize gitit and wrote the
433 InterwikiPlugin.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
434 - Simon Michael contributed the patch adding RST support.
435 - Henry Laxen added support for password resets and helped with
436 the apache proxy instructions.
437 - Anton van Straaten made the process of page generation
438 more modular by adding Gitit.ContentTransformer.
058ce02 @jgm Acknowledge Robin Green's patch in README.
authored
439 - Robin Green helped improve the plugin API and interface, and
440 fixed a security problem with the reset password code.
edeca79 More acknowledgements.
John MacFarlane authored
441 - Thomas Hartman helped improve the index page, making directory
442 browsing persistent.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
443 - Justin Bogner improved the appearance of the preview button.
8500b29 @jgm More contributors.
authored
444 - Kohei Ozaki contributed the ImgTexPlugin.
cf6e15e @jgm Added acknowledgement for mightybyte.
authored
445 - mightybyte suggested making gitit available as a library,
446 and contributed a patch to ifLoggedIn that was needed to
447 make gitit usable with a custom authentication scheme.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
448
449 Gitit's default visual layout is shamelessly borrowed from Wikipedia.
5c5c337 @jgm Updated README.
authored
450 The stylesheets are influenced by Wikipedia's stylesheets and by the
451 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
452 `img/icons` come from bluetrip as well.
453
Something went wrong with that request. Please try again.