Skip to content
This repository
Newer
Older
100644 399 lines (290 sloc) 14.205 kb
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
1 Gitit
2 =====
89725fd9 »
2008-11-06 Initial commit.
3
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
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
0f4f9c6e »
2009-06-05 Indicate in README that LaTeX or HTML formats can be used.
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][]).
89725fd9 »
2008-11-06 Initial commit.
14
15 [git]: http://git.or.cz
d9c8cd8b »
2009-01-24 Modified description slightly, mentioning darcs as well as git.
16 [darcs]: http://darcs.net
89725fd9 »
2008-11-06 Initial commit.
17 [pandoc]: http://johnmacfarlane.net/pandoc
fd9eed57 »
2009-03-10 Changed mentions of HAppS to Happstack.
18 [Happstack]: http://happstack.com
f8cd0519 »
2008-11-22 Updated README.
19 [jsMath]: http://www.math.union.edu/~dpvc/jsMath/
20 [highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/
89725fd9 »
2008-11-06 Initial commit.
21
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
22 Getting started
23 ===============
89725fd9 »
2008-11-06 Initial commit.
24
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
25 Compiling and installing gitit
26 ------------------------------
89725fd9 »
2008-11-06 Initial commit.
27
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
28 You'll need the [GHC][] compiler and the [cabal-install][] tool. GHC can
98adca8b »
2009-01-28 Note the GHC 6.10 requirement in README.
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
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
31 install][] instructions.
89725fd9 »
2008-11-06 Initial commit.
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
97e00433 » John MacFarlane
2009-04-18 Improved README.
38 Once you've got cabal-install, installing gitit is trivial:
89725fd9 »
2008-11-06 Initial commit.
39
a7c11fe8 »
2008-11-30 Simplified installation instructions.
40 cabal update
89725fd9 »
2008-11-06 Initial commit.
41 cabal install gitit
42
a7c11fe8 »
2008-11-30 Simplified installation instructions.
43 These commands will install the latest released version of gitit.
89725fd9 »
2008-11-06 Initial commit.
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
97e00433 » John MacFarlane
2009-04-18 Improved README.
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
1f07157d »
2009-02-16 Slightly improved plugins documentation.
78 Optional plugins support
79 ------------------------
80
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
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.
3da0cc88 »
2009-06-14 Fixed plugins to use new Network.Gitit prefix.
85 (If the plugin name starts with `Network.Gitit.Plugin.`, gitit will assume that
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
86 the plugin is an installed module and will not look for a source file.)
1f07157d »
2009-02-16 Slightly improved plugins documentation.
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
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
97 Running gitit
98 -------------
89725fd9 »
2008-11-06 Initial commit.
99
97e00433 » John MacFarlane
2009-04-18 Improved README.
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.)
89725fd9 »
2008-11-06 Initial commit.
102
97e00433 » John MacFarlane
2009-04-18 Improved README.
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`.)
73db5a1f »
2009-01-28 Noted need for UTF-8 locale in README.
107
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
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:
89725fd9 »
2008-11-06 Initial commit.
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.
97e00433 » John MacFarlane
2009-04-18 Improved README.
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
f498fc6d »
2008-11-26 Use HStringTemplate template for pages.
121 for wiki pages.
122 4. Start a web server on port 5001.
89725fd9 »
2008-11-06 Initial commit.
123
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
124 Check that it worked: open a web browser and go to
125 <http://localhost:5001>.
97e00433 » John MacFarlane
2009-04-18 Improved README.
126
127 Wiki links and formatting
128 -------------------------
129
130 For instructions on editing pages and creating links, see the "Help" page.
131
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
132 Gitit interprets links with empty URLs as wikilinks. Thus, in markdown
133 pages, `[Front Page]()` creates an internal wikilink to the page `Front
134 Page`. In reStructuredText pages, `` `Front Page <>`_ `` has the same
135 effect.
89725fd9 »
2008-11-06 Initial commit.
136
c332b942 »
2009-05-10 Documentation changes for new index link format.
137 If you want to link to a directory listing for a subdirectory, use a
138 trailing slash: `[foo/bar/]()` creates a link to the directory for
139 `foo/bar`.
140
488e6bbc » John MacFarlane
2009-04-18 README: Added instructions for proxying with apache.
141 Configuring gitit
142 =================
143
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
144 Configuration options
145 ---------------------
89725fd9 »
2008-11-06 Initial commit.
146
147 You can set some configuration options when starting gitit, using the
ce07825b »
2009-04-12 Added data/default.conf, which defines default config file values.
148 option `-f [filename]`. To get a copy of the default configuration file,
149 which you can customize, just type:
150
151 gitit --print-default-config > default.conf
152
153 The default configuration file is documented with comments throughout.
2859d1b4 »
2009-02-10 Document --print-default-config.
154
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
155 The `static` directory
156 ----------------------
89725fd9 »
2008-11-06 Initial commit.
157
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
158 If there is no wiki page or uploaded file corresponding to a request,
159 gitit always looks last in the `static` directory. So, for example,
160 a file `foo.jpg` in the `img` subdirectory of the `static` directory
161 will be accessible at the url `/img/foo.jpg`. Pandoc creates three
162 subdirectories of `static`, `css`, `img`, and `js`, which include the
163 icons, stylesheets, and javascripts it uses.
89725fd9 »
2008-11-06 Initial commit.
164
77d20a35 »
2009-04-27 README changes: running with darcs, updated some refs to config options.
165 Note: if you set `static-dir` to be a subdirectory of `repository-path`,
89e0a04b »
2009-01-16 Added note about possibility of putting static inside repository.
166 and then add the files in the static directory to your repository, you
167 can ensure that others who clone your wiki repository get these files
168 as well. It will not be possible to modify these files using the web
169 interface, but they will be modifiable via git.
170
77d20a35 »
2009-04-27 README changes: running with darcs, updated some refs to config options.
171 Using darcs instead of git
172 --------------------------
173
174 By default, gitit will store wiki pages in a git repository in the
175 `wikidata` directory. If you'd prefer to use darcs instead of git,
176 you need to add the following field to the configuration file:
177
178 repository-type: Darcs
179
180 This program may be called "darcsit" instead of "gitit" when a darcs
181 backend is used.
182
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
183 Changing the theme
184 ------------------
89725fd9 »
2008-11-06 Initial commit.
185
97e00433 » John MacFarlane
2009-04-18 Improved README.
186 To change the look of the wiki, you can modify `screen.css` in
187 `static/css`. But a better approach is to add a line to `template.html`
188 that imports your own custom stylesheet. This line should go
189 after the line that links to `/css/screen.css`:
190
191 <link href="/css/my-screen.css" rel="stylesheet" media="screen, projection" type="text/css" />
192
193 Then add `my-screen.css` to the `static/css` directory and customize
194 it as you see fit. The advantage of this approach is that you won't
195 need to merge changes in `screen.css` when gitit is updated. You can
196 just copy the revised `screen.css` into your `static/css` directory.
197
5c5c3374 »
2008-11-22 Updated README.
198 To change the look of printed pages, modify `print.css`.
97e00433 » John MacFarlane
2009-04-18 Improved README.
199
f498fc6d »
2008-11-26 Use HStringTemplate template for pages.
200 The logo picture can be changed by copying a new PNG file to
97e00433 » John MacFarlane
2009-04-18 Improved README.
201 `static/img/logo.png`.
202
203 For more radical changes, you can modify `template.html`.
204 Note that interpolated variables are surrounded by `$`s, so literal
205 `$` must be backslash-escaped.
89725fd9 »
2008-11-06 Initial commit.
206
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
207 Adding support for math
208 -----------------------
89725fd9 »
2008-11-06 Initial commit.
209
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
210 Gitit is designed to work with [jsMath][] to display LaTeX math in
211 HTML. Download `jsMath` and `jsMath Image Fonts` from the [jsMath
212 download page][]. You'll have two `.zip` archives. Unzip them both
213 in the `static/js` directory (a new subdirectory, `jsMath`, will be
214 created). You can test to see if math is working properly by clicking
215 "help" on the top navigation bar and looking for the math example (the
216 quadratic formula). Note that if you copied the `jsMath` directory into
217 `static` *after* starting gitit, you will have to restart gitit for the
218 change to be noticed. Gitit checks for the existence of the jsMath files
219 when it starts, and will not include links to them unless they exist.
89725fd9 »
2008-11-06 Initial commit.
220
221 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
222
223 Here is a formula: $\frac{1}{\sqrt{c^2}}$
224
225 You can write display math by enclosing it in double dollar signs:
226
227 $$\frac{1}{\sqrt{c^2}}$$
228
229 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
230
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
231 Highlighted source code
232 -----------------------
89725fd9 »
2008-11-06 Initial commit.
233
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
234 If gitit was compiled against a version of pandoc that has highlighting
235 support (see above), you can get highlighted source code by using
236 [delimited code blocks][]:
89725fd9 »
2008-11-06 Initial commit.
237
238 ~~~ {.haskell .numberLines}
239 qsort [] = []
240 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
241 qsort (filter (>= x) xs)
242 ~~~
243
244 To see what languages are available:
245
246 pandoc -v
247
248 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
249
77d20a35 »
2009-04-27 README changes: running with darcs, updated some refs to config options.
250 Accessing the wiki via git or darcs
251 ===================================
89725fd9 »
2008-11-06 Initial commit.
252
77d20a35 »
2009-04-27 README changes: running with darcs, updated some refs to config options.
253 All the pages and uploaded files are stored in a git or darcs
254 repository. By default, this lives in the `wikidata` directory (though
255 this can be changed through configuration options). So you can interact
256 with the wiki using git command line tools:
89725fd9 »
2008-11-06 Initial commit.
257
258 git clone ssh://my.server.edu/path/of/wiki/wikidata
259 cd wikidata
260 vim Front\ Page.page # edit the page
261 git commit -m "Added message about wiki etiquette" Front\ Page.page
262 git push
263
264 If you now look at the Front Page on the wiki, you should see your changes
265 reflected there. Note that the pages all have the extension `.page`.
266
488e6bbc » John MacFarlane
2009-04-18 README: Added instructions for proxying with apache.
267 Using gitit with apache
268 =======================
269
270 Most users who run a public-facing gitit will want gitit to appear
271 at a nice URL like `http://wiki.mysite.com` or
272 `http://mysite.com/wiki` rather than `http://mysite.com:5001`.
273 This can be achieved using apache's `mod_proxy`.
274
275 Proxying to `http://wiki.mysite.com`
276 ------------------------------------
277
278 Set up your DNS so that `http://wiki.mysite.com` maps to
279 your server's IP address. Make sure that the `mod_proxy` module is
280 loaded, and set up a virtual host with the following configuration:
281
282 <VirtualHost *>
283 ServerName wiki.mysite.com
284 DocumentRoot /var/www/
285 RewriteEngine On
286 ProxyPreserveHost On
287 ProxyRequests Off
288
289 <Proxy *>
290 Order deny,allow
291 Allow from all
292 </Proxy>
293
294 ProxyPassReverse / http://127.0.0.1:5001
295 RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
296
297 ErrorLog /var/log/apache2/error.log
298 LogLevel warn
299
300 CustomLog /var/log/apache2/access.log combined
301 ServerSignature On
302
303 </VirtualHost>
304
305 Reload your apache configuration and you should be all set.
306
307 Proxying to `http://mysite.com/wiki`
308 ------------------------------------
309
310 Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
311 and `mod_proxy_html` modules are loaded. `mod_proxy_html`
312 is an external module, which can be obtained [here]
313 (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
314 occur in web pages. Here we will use it to rewrite gitit's links so that
315 they all begin with `/wiki/`.
316
f8ab67e6 »
2009-04-27 Reformatting (line lengths) of README.
317 First, tell gitit not to compress pages, since `mod_proxy_html` needs
318 uncompressed pages to parse. You can do this by setting the gitit
319 configuration option
488e6bbc » John MacFarlane
2009-04-18 README: Added instructions for proxying with apache.
320
77d20a35 »
2009-04-27 README changes: running with darcs, updated some refs to config options.
321 compress-responses: no
322
323 Second, modify the link in the `reset-password-message` in the
324 configuration file: instead of
325
326 http://$hostname$:$port$$resetlink$
327
328 set it to
329
330 http://$hostname$/wiki$resetlink$
488e6bbc » John MacFarlane
2009-04-18 README: Added instructions for proxying with apache.
331
332 Restart gitit.
333
334 Now add the following lines to the apache configuration file for the
335 `mysite.com` server:
336
337 # These commands will proxy /wiki/ to port 5001
338
339 ProxyRequests Off
340
341 <Proxy *>
342 Order deny,allow
343 Allow from all
344 </Proxy>
345
346 ProxyPass /wiki/ http://127.0.0.1:5001/
347
348 <Location /wiki/>
349 SetOutputFilter proxy-html
350 ProxyPassReverse /
351 ProxyHTMLURLMap / /wiki/
352 RequestHeader unset Accept-Encoding
353 </Location>
354
355 Reload your apache configuration and you should be set.
356
357 For further information on the use of `mod_proxy_http` to rewrite URLs,
358 see the [`mod_proxy_html` guide].
359
360 [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
361
e86d3dce »
2009-06-24 Added note on using gitit as a library to README.
362 Using gitit as a library
363 ========================
364
365 By importing the module `Network.Gitit`, you can include a gitit wiki
366 (or several of them) in another happstack application. There are some
367 simple examples in the haddock documentation for `Network.Gitit`.
368
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
369 Reporting bugs
370 ==============
89725fd9 »
2008-11-06 Initial commit.
371
a49ba22c »
2008-12-07 Added link to bug tracker on googlecode.
372 Bugs may be reported (and feature requests filed) at
373 <http://code.google.com/p/gitit/issues/list>.
89725fd9 »
2008-11-06 Initial commit.
374
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
375 Acknowledgements
376 ================
89725fd9 »
2008-11-06 Initial commit.
377
bb8abc3a »
2009-04-27 Improved acknowledgements, bringing list of contributors up to date.
378 A number of people have contributed patches:
379
8500b29a »
2009-04-27 More contributors.
380 - Gwern Branwen helped to optimize gitit and wrote the
381 InterwikiPlugin.
bb8abc3a »
2009-04-27 Improved acknowledgements, bringing list of contributors up to date.
382 - Simon Michael contributed the patch adding RST support.
383 - Henry Laxen added support for password resets and helped with
384 the apache proxy instructions.
385 - Anton van Straaten made the process of page generation
386 more modular by adding Gitit.ContentTransformer.
387 - Robin Green helped improve the plugin API and interface.
edeca79e » John MacFarlane
2009-04-27 More acknowledgements.
388 - Thomas Hartman helped improve the index page, making directory
389 browsing persistent.
bb8abc3a »
2009-04-27 Improved acknowledgements, bringing list of contributors up to date.
390 - Justin Bogner improved the appearance of the preview button.
8500b29a »
2009-04-27 More contributors.
391 - Kohei Ozaki contributed the ImgTexPlugin.
cf6e15e1 »
2009-06-24 Added acknowledgement for mightybyte.
392 - mightybyte suggested making gitit available as a library,
393 and contributed a patch to ifLoggedIn that was needed to
394 make gitit usable with a custom authentication scheme.
bb8abc3a »
2009-04-27 Improved acknowledgements, bringing list of contributors up to date.
395
396 Gitit's default visual layout is shamelessly borrowed from Wikipedia.
5c5c3374 »
2008-11-22 Updated README.
397 The stylesheets are influenced by Wikipedia's stylesheets and by the
398 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
399 `img/icons` come from bluetrip as well.
400
Something went wrong with that request. Please try again.