Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 383 lines (275 sloc) 13.434 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
9 is used as a markup language, but reStructuredText can also be used.
10 Pages can be exported in a number of different formats, including LaTeX,
11 RTF, OpenOffice ODT, and MediaWiki markup. Gitit can be configured to
12 display TeX math (using [jsMath][]) and highlighted source code (using
13 [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.
85 (If the plugin name starts with `Gitit.Plugin.`, gitit will assume that
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
127 Wiki links and formatting
128 -------------------------
129
130 For instructions on editing pages and creating links, see the "Help" page.
131
f8ab67e @jgm Reformatting (line lengths) of README.
authored
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.
89725fd @jgm Initial commit.
authored
136
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
137 Configuring gitit
138 =================
139
45a9c7f @jgm Reformatted README using standard markdown.
authored
140 Configuration options
141 ---------------------
89725fd @jgm Initial commit.
authored
142
143 You can set some configuration options when starting gitit, using the
ce07825 @jgm Added data/default.conf, which defines default config file values.
authored
144 option `-f [filename]`. To get a copy of the default configuration file,
145 which you can customize, just type:
146
147 gitit --print-default-config > default.conf
148
149 The default configuration file is documented with comments throughout.
2859d1b @jgm Document --print-default-config.
authored
150
45a9c7f @jgm Reformatted README using standard markdown.
authored
151 The `static` directory
152 ----------------------
89725fd @jgm Initial commit.
authored
153
f8ab67e @jgm Reformatting (line lengths) of README.
authored
154 If there is no wiki page or uploaded file corresponding to a request,
155 gitit always looks last in the `static` directory. So, for example,
156 a file `foo.jpg` in the `img` subdirectory of the `static` directory
157 will be accessible at the url `/img/foo.jpg`. Pandoc creates three
158 subdirectories of `static`, `css`, `img`, and `js`, which include the
159 icons, stylesheets, and javascripts it uses.
89725fd @jgm Initial commit.
authored
160
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
161 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
162 and then add the files in the static directory to your repository, you
163 can ensure that others who clone your wiki repository get these files
164 as well. It will not be possible to modify these files using the web
165 interface, but they will be modifiable via git.
166
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
167 Using darcs instead of git
168 --------------------------
169
170 By default, gitit will store wiki pages in a git repository in the
171 `wikidata` directory. If you'd prefer to use darcs instead of git,
172 you need to add the following field to the configuration file:
173
174 repository-type: Darcs
175
176 This program may be called "darcsit" instead of "gitit" when a darcs
177 backend is used.
178
45a9c7f @jgm Reformatted README using standard markdown.
authored
179 Changing the theme
180 ------------------
89725fd @jgm Initial commit.
authored
181
97e0043 Improved README.
John MacFarlane authored
182 To change the look of the wiki, you can modify `screen.css` in
183 `static/css`. But a better approach is to add a line to `template.html`
184 that imports your own custom stylesheet. This line should go
185 after the line that links to `/css/screen.css`:
186
187 <link href="/css/my-screen.css" rel="stylesheet" media="screen, projection" type="text/css" />
188
189 Then add `my-screen.css` to the `static/css` directory and customize
190 it as you see fit. The advantage of this approach is that you won't
191 need to merge changes in `screen.css` when gitit is updated. You can
192 just copy the revised `screen.css` into your `static/css` directory.
193
5c5c337 @jgm Updated README.
authored
194 To change the look of printed pages, modify `print.css`.
97e0043 Improved README.
John MacFarlane authored
195
f498fc6 @jgm Use HStringTemplate template for pages.
authored
196 The logo picture can be changed by copying a new PNG file to
97e0043 Improved README.
John MacFarlane authored
197 `static/img/logo.png`.
198
199 For more radical changes, you can modify `template.html`.
200 Note that interpolated variables are surrounded by `$`s, so literal
201 `$` must be backslash-escaped.
89725fd @jgm Initial commit.
authored
202
45a9c7f @jgm Reformatted README using standard markdown.
authored
203 Adding support for math
204 -----------------------
89725fd @jgm Initial commit.
authored
205
f8ab67e @jgm Reformatting (line lengths) of README.
authored
206 Gitit is designed to work with [jsMath][] to display LaTeX math in
207 HTML. Download `jsMath` and `jsMath Image Fonts` from the [jsMath
208 download page][]. You'll have two `.zip` archives. Unzip them both
209 in the `static/js` directory (a new subdirectory, `jsMath`, will be
210 created). You can test to see if math is working properly by clicking
211 "help" on the top navigation bar and looking for the math example (the
212 quadratic formula). Note that if you copied the `jsMath` directory into
213 `static` *after* starting gitit, you will have to restart gitit for the
214 change to be noticed. Gitit checks for the existence of the jsMath files
215 when it starts, and will not include links to them unless they exist.
89725fd @jgm Initial commit.
authored
216
217 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
218
219 Here is a formula: $\frac{1}{\sqrt{c^2}}$
220
221 You can write display math by enclosing it in double dollar signs:
222
223 $$\frac{1}{\sqrt{c^2}}$$
224
225 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
226
45a9c7f @jgm Reformatted README using standard markdown.
authored
227 Highlighted source code
228 -----------------------
89725fd @jgm Initial commit.
authored
229
f8ab67e @jgm Reformatting (line lengths) of README.
authored
230 If gitit was compiled against a version of pandoc that has highlighting
231 support (see above), you can get highlighted source code by using
232 [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
233
234 ~~~ {.haskell .numberLines}
235 qsort [] = []
236 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
237 qsort (filter (>= x) xs)
238 ~~~
239
240 To see what languages are available:
241
242 pandoc -v
243
244 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
245
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
246 Accessing the wiki via git or darcs
247 ===================================
89725fd @jgm Initial commit.
authored
248
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
249 All the pages and uploaded files are stored in a git or darcs
250 repository. By default, this lives in the `wikidata` directory (though
251 this can be changed through configuration options). So you can interact
252 with the wiki using git command line tools:
89725fd @jgm Initial commit.
authored
253
254 git clone ssh://my.server.edu/path/of/wiki/wikidata
255 cd wikidata
256 vim Front\ Page.page # edit the page
257 git commit -m "Added message about wiki etiquette" Front\ Page.page
258 git push
259
260 If you now look at the Front Page on the wiki, you should see your changes
261 reflected there. Note that the pages all have the extension `.page`.
262
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
263 Using gitit with apache
264 =======================
265
266 Most users who run a public-facing gitit will want gitit to appear
267 at a nice URL like `http://wiki.mysite.com` or
268 `http://mysite.com/wiki` rather than `http://mysite.com:5001`.
269 This can be achieved using apache's `mod_proxy`.
270
271 Proxying to `http://wiki.mysite.com`
272 ------------------------------------
273
274 Set up your DNS so that `http://wiki.mysite.com` maps to
275 your server's IP address. Make sure that the `mod_proxy` module is
276 loaded, and set up a virtual host with the following configuration:
277
278 <VirtualHost *>
279 ServerName wiki.mysite.com
280 DocumentRoot /var/www/
281 RewriteEngine On
282 ProxyPreserveHost On
283 ProxyRequests Off
284
285 <Proxy *>
286 Order deny,allow
287 Allow from all
288 </Proxy>
289
290 ProxyPassReverse / http://127.0.0.1:5001
291 RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
292
293 ErrorLog /var/log/apache2/error.log
294 LogLevel warn
295
296 CustomLog /var/log/apache2/access.log combined
297 ServerSignature On
298
299 </VirtualHost>
300
301 Reload your apache configuration and you should be all set.
302
303 Proxying to `http://mysite.com/wiki`
304 ------------------------------------
305
306 Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
307 and `mod_proxy_html` modules are loaded. `mod_proxy_html`
308 is an external module, which can be obtained [here]
309 (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
310 occur in web pages. Here we will use it to rewrite gitit's links so that
311 they all begin with `/wiki/`.
312
f8ab67e @jgm Reformatting (line lengths) of README.
authored
313 First, tell gitit not to compress pages, since `mod_proxy_html` needs
314 uncompressed pages to parse. You can do this by setting the gitit
315 configuration option
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
316
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
317 compress-responses: no
318
319 Second, modify the link in the `reset-password-message` in the
320 configuration file: instead of
321
322 http://$hostname$:$port$$resetlink$
323
324 set it to
325
326 http://$hostname$/wiki$resetlink$
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
327
328 Restart gitit.
329
330 Now add the following lines to the apache configuration file for the
331 `mysite.com` server:
332
333 # These commands will proxy /wiki/ to port 5001
334
335 ProxyRequests Off
336
337 <Proxy *>
338 Order deny,allow
339 Allow from all
340 </Proxy>
341
342 ProxyPass /wiki/ http://127.0.0.1:5001/
343
344 <Location /wiki/>
345 SetOutputFilter proxy-html
346 ProxyPassReverse /
347 ProxyHTMLURLMap / /wiki/
348 RequestHeader unset Accept-Encoding
349 </Location>
350
351 Reload your apache configuration and you should be set.
352
353 For further information on the use of `mod_proxy_http` to rewrite URLs,
354 see the [`mod_proxy_html` guide].
355
356 [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
357
45a9c7f @jgm Reformatted README using standard markdown.
authored
358 Reporting bugs
359 ==============
89725fd @jgm Initial commit.
authored
360
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
361 Bugs may be reported (and feature requests filed) at
362 <http://code.google.com/p/gitit/issues/list>.
89725fd @jgm Initial commit.
authored
363
45a9c7f @jgm Reformatted README using standard markdown.
authored
364 Acknowledgements
365 ================
89725fd @jgm Initial commit.
authored
366
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
367 A number of people have contributed patches:
368
369 - Gwern Branwen helped to optimize gitit.
370 - Simon Michael contributed the patch adding RST support.
371 - Henry Laxen added support for password resets and helped with
372 the apache proxy instructions.
373 - Anton van Straaten made the process of page generation
374 more modular by adding Gitit.ContentTransformer.
375 - Robin Green helped improve the plugin API and interface.
376 - Justin Bogner improved the appearance of the preview button.
377
378 Gitit's default visual layout is shamelessly borrowed from Wikipedia.
5c5c337 @jgm Updated README.
authored
379 The stylesheets are influenced by Wikipedia's stylesheets and by the
380 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
381 `img/icons` come from bluetrip as well.
382
Something went wrong with that request. Please try again.