Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 374 lines (266 sloc) 13.112 kb
45a9c7f @jgm Reformatted README using standard markdown.
authored
1 Gitit
2 =====
89725fd @jgm Initial commit.
authored
3
fd9eed5 @jgm Changed mentions of HAppS to Happstack.
authored
4 Gitit is a wiki program written in Haskell. It uses [Happstack][] for the
d9c8cd8 @jgm Modified description slightly, mentioning darcs as well as git.
authored
5 web server and [pandoc][] for markup processing. Pages and uploaded
6 files are stored in a [git][] or [darcs][] repository and may be modified either
7 by using the VCS's command-line tools or through the wiki's web interface.
16f9dde @jgm Updated configuration section of README.
authored
8 By default, pandoc's extended version of markdown is used as a markup language,
9 but reStructuredText can also be used. Pages can be exported in a
10 number of different formats, including LaTeX, RTF, OpenOffice ODT, and
11 MediaWiki markup. Gitit can be configured to display TeX math (using
12 [jsMath][]) and highlighted source code (using [highlighting-kate][]).
89725fd @jgm Initial commit.
authored
13
14 [git]: http://git.or.cz
d9c8cd8 @jgm Modified description slightly, mentioning darcs as well as git.
authored
15 [darcs]: http://darcs.net
89725fd @jgm Initial commit.
authored
16 [pandoc]: http://johnmacfarlane.net/pandoc
fd9eed5 @jgm Changed mentions of HAppS to Happstack.
authored
17 [Happstack]: http://happstack.com
f8cd051 @jgm Updated README.
authored
18 [jsMath]: http://www.math.union.edu/~dpvc/jsMath/
19 [highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/
89725fd @jgm Initial commit.
authored
20
45a9c7f @jgm Reformatted README using standard markdown.
authored
21 Getting started
22 ===============
89725fd @jgm Initial commit.
authored
23
45a9c7f @jgm Reformatted README using standard markdown.
authored
24 Compiling and installing gitit
25 ------------------------------
89725fd @jgm Initial commit.
authored
26
45a9c7f @jgm Reformatted README using standard markdown.
authored
27 You'll need the [GHC][] compiler and the [cabal-install][] tool. GHC can
98adca8 @jgm Note the GHC 6.10 requirement in README.
authored
28 be downloaded [here][]. Note that, starting with release 0.5, GHC 6.10
29 or higher is required. For [cabal-install][] on *nix, follow the [quick
45a9c7f @jgm Reformatted README using standard markdown.
authored
30 install][] instructions.
89725fd @jgm Initial commit.
authored
31
32 [GHC]: http://www.haskell.org/ghc/
33 [here]: http://www.haskell.org/ghc/
34 [cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
35 [quick install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick Installation on Unix
36
97e0043 Improved README.
John MacFarlane authored
37 Once you've got cabal-install, installing gitit is trivial:
89725fd @jgm Initial commit.
authored
38
a7c11fe @jgm Simplified installation instructions.
authored
39 cabal update
89725fd @jgm Initial commit.
authored
40 cabal install gitit
41
a7c11fe @jgm Simplified installation instructions.
authored
42 These commands will install the latest released version of gitit.
89725fd @jgm Initial commit.
authored
43 To install a version of gitit checked out from the repository,
44 change to the gitit directory and type:
45
46 cabal install
47
48 The `cabal` tool will automatically install all of the required haskell
49 libraries. If all goes well, by the end of this process, the latest
50 release of gitit will be installed in your local `.cabal` directory. You
51 can check this by trying:
52
53 gitit --version
54
55 If that doesn't work, check to see that `gitit` is in your local
56 cabal-install executable directory (usually `~/.cabal/bin`). And make
57 sure `~/.cabal/bin` is in your system path.
58
97e0043 Improved README.
John MacFarlane authored
59 Optional syntax highlighting support
60 ------------------------------------
61
62 If pandoc was compiled with optional syntax highlighting support,
63 this will be available in gitit too. This feature is recommended
64 if you plan to display source code on your wiki.
65
66 Highlighting support requires the [pcre][] library, so make sure that
67 is installed before continuing.
68
69 [pcre]: http://www.pcre.org/
70
71 To install gitit with highlighting support, first ensure that pandoc
72 is compiled with highlighting support, then install gitit as above:
73
74 cabal install pandoc -fhighlighting --reinstall
75 cabal install gitit
76
1f07157 @jgm Slightly improved plugins documentation.
authored
77 Optional plugins support
78 ------------------------
79
80 Plugins are small Haskell programs that transform a wiki page
81 after it has been converted from Markdown or RST. See the example
ddd1301 @jgm Redescribed plugin directory in README.markdown.
authored
82 plugins in the `plugins` directory. To enable a plugin, include the path
97e0043 Improved README.
John MacFarlane authored
83 to the plugin (or its module name) in the `plugins` field of the
128b8e9 @jgm Plugins beginning "Gitit.Plugin." are assumed to be installed modules.
authored
84 configuration file. (If the plugin name starts with `Gitit.Plugin.`,
85 gitit will assume that the plugin is an installed module and will not
86 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
89725fd @jgm Initial commit.
authored
108 Switch to the directory where you want to run gitit. This should be a directory
5c5c337 @jgm Updated README.
authored
109 where you have write access, since two directories, `static` and `wikidata`, and
f498fc6 @jgm Use HStringTemplate template for pages.
authored
110 two files, `gitit-users` and `template.html`, will be created here. To
111 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
97e0043 Improved README.
John MacFarlane authored
124 Check that it worked: open a web browser and go to <http://localhost:5001>.
125
126 Wiki links and formatting
127 -------------------------
128
129 For instructions on editing pages and creating links, see the "Help" page.
130
131 Gitit interprets links with empty URLs as wikilinks. Thus, in markdown pages,
132 `[Front Page]()` creates an internal wikilink to the page `Front Page`.
133 In reStructuredText pages, `` `Front Page <>`_ `` has the same effect.
89725fd @jgm Initial commit.
authored
134
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
135 Configuring gitit
136 =================
137
45a9c7f @jgm Reformatted README using standard markdown.
authored
138 Configuration options
139 ---------------------
89725fd @jgm Initial commit.
authored
140
141 You can set some configuration options when starting gitit, using the
ce07825 @jgm Added data/default.conf, which defines default config file values.
authored
142 option `-f [filename]`. To get a copy of the default configuration file,
143 which you can customize, just type:
144
145 gitit --print-default-config > default.conf
146
147 The default configuration file is documented with comments throughout.
2859d1b @jgm Document --print-default-config.
authored
148
45a9c7f @jgm Reformatted README using standard markdown.
authored
149 The `static` directory
150 ----------------------
89725fd @jgm Initial commit.
authored
151
152 If there is no wiki page or uploaded file corresponding to a request, gitit
153 always looks last in the `static` directory. So, for example, a file
5c5c337 @jgm Updated README.
authored
154 `foo.jpg` in the `img` subdirectory of the `static` directory will be
155 accessible at the url `/img/foo.jpg`. Pandoc creates three subdirectories
156 of `static`, `css`, `img`, and `js`, which include the icons, stylesheets,
157 and javascripts it uses.
89725fd @jgm Initial commit.
authored
158
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
159 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
160 and then add the files in the static directory to your repository, you
161 can ensure that others who clone your wiki repository get these files
162 as well. It will not be possible to modify these files using the web
163 interface, but they will be modifiable via git.
164
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
165 Using darcs instead of git
166 --------------------------
167
168 By default, gitit will store wiki pages in a git repository in the
169 `wikidata` directory. If you'd prefer to use darcs instead of git,
170 you need to add the following field to the configuration file:
171
172 repository-type: Darcs
173
174 This program may be called "darcsit" instead of "gitit" when a darcs
175 backend is used.
176
45a9c7f @jgm Reformatted README using standard markdown.
authored
177 Changing the theme
178 ------------------
89725fd @jgm Initial commit.
authored
179
97e0043 Improved README.
John MacFarlane authored
180 To change the look of the wiki, you can modify `screen.css` in
181 `static/css`. But a better approach is to add a line to `template.html`
182 that imports your own custom stylesheet. This line should go
183 after the line that links to `/css/screen.css`:
184
185 <link href="/css/my-screen.css" rel="stylesheet" media="screen, projection" type="text/css" />
186
187 Then add `my-screen.css` to the `static/css` directory and customize
188 it as you see fit. The advantage of this approach is that you won't
189 need to merge changes in `screen.css` when gitit is updated. You can
190 just copy the revised `screen.css` into your `static/css` directory.
191
5c5c337 @jgm Updated README.
authored
192 To change the look of printed pages, modify `print.css`.
97e0043 Improved README.
John MacFarlane authored
193
f498fc6 @jgm Use HStringTemplate template for pages.
authored
194 The logo picture can be changed by copying a new PNG file to
97e0043 Improved README.
John MacFarlane authored
195 `static/img/logo.png`.
196
197 For more radical changes, you can modify `template.html`.
198 Note that interpolated variables are surrounded by `$`s, so literal
199 `$` must be backslash-escaped.
89725fd @jgm Initial commit.
authored
200
45a9c7f @jgm Reformatted README using standard markdown.
authored
201 Adding support for math
202 -----------------------
89725fd @jgm Initial commit.
authored
203
45a9c7f @jgm Reformatted README using standard markdown.
authored
204 Gitit is designed to work with [jsMath][] to display LaTeX math in HTML.
205 Download `jsMath` and `jsMath Image Fonts` from the [jsMath download page][].
89725fd @jgm Initial commit.
authored
206 You'll have two `.zip` archives. Unzip them both in the
5c5c337 @jgm Updated README.
authored
207 `static/js` directory (a new subdirectory, `jsMath`, will be
89725fd @jgm Initial commit.
authored
208 created). You can test to see if math is working properly by clicking
209 "help" on the top navigation bar and looking for the math example
483e9fb @jgm Added explanatory note about jsMath to README.
authored
210 (the quadratic formula). Note that if you copied the `jsMath` directory
211 into `static` *after* starting gitit, you will have to restart gitit
212 for the change to be noticed. Gitit checks for the existence of the
213 jsMath files when it starts, and will not include links to them unless
214 they exist.
89725fd @jgm Initial commit.
authored
215
216 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
217
218 Here is a formula: $\frac{1}{\sqrt{c^2}}$
219
220 You can write display math by enclosing it in double dollar signs:
221
222 $$\frac{1}{\sqrt{c^2}}$$
223
224 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
225
45a9c7f @jgm Reformatted README using standard markdown.
authored
226 Highlighted source code
227 -----------------------
89725fd @jgm Initial commit.
authored
228
229 If gitit was compiled against a version of pandoc that has highlighting support
45a9c7f @jgm Reformatted README using standard markdown.
authored
230 (see above), you can get highlighted source code by using [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
231
232 ~~~ {.haskell .numberLines}
233 qsort [] = []
234 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
235 qsort (filter (>= x) xs)
236 ~~~
237
238 To see what languages are available:
239
240 pandoc -v
241
242 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
243
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
244 Accessing the wiki via git or darcs
245 ===================================
89725fd @jgm Initial commit.
authored
246
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
247 All the pages and uploaded files are stored in a git or darcs
248 repository. By default, this lives in the `wikidata` directory (though
249 this can be changed through configuration options). So you can interact
250 with the wiki using git command line tools:
89725fd @jgm Initial commit.
authored
251
252 git clone ssh://my.server.edu/path/of/wiki/wikidata
253 cd wikidata
254 vim Front\ Page.page # edit the page
255 git commit -m "Added message about wiki etiquette" Front\ Page.page
256 git push
257
258 If you now look at the Front Page on the wiki, you should see your changes
259 reflected there. Note that the pages all have the extension `.page`.
260
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
261 Using gitit with apache
262 =======================
263
264 Most users who run a public-facing gitit will want gitit to appear
265 at a nice URL like `http://wiki.mysite.com` or
266 `http://mysite.com/wiki` rather than `http://mysite.com:5001`.
267 This can be achieved using apache's `mod_proxy`.
268
269 Proxying to `http://wiki.mysite.com`
270 ------------------------------------
271
272 Set up your DNS so that `http://wiki.mysite.com` maps to
273 your server's IP address. Make sure that the `mod_proxy` module is
274 loaded, and set up a virtual host with the following configuration:
275
276 <VirtualHost *>
277 ServerName wiki.mysite.com
278 DocumentRoot /var/www/
279 RewriteEngine On
280 ProxyPreserveHost On
281 ProxyRequests Off
282
283 <Proxy *>
284 Order deny,allow
285 Allow from all
286 </Proxy>
287
288 ProxyPassReverse / http://127.0.0.1:5001
289 RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
290
291 ErrorLog /var/log/apache2/error.log
292 LogLevel warn
293
294 CustomLog /var/log/apache2/access.log combined
295 ServerSignature On
296
297 </VirtualHost>
298
299 Reload your apache configuration and you should be all set.
300
301 Proxying to `http://mysite.com/wiki`
302 ------------------------------------
303
304 Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
305 and `mod_proxy_html` modules are loaded. `mod_proxy_html`
306 is an external module, which can be obtained [here]
307 (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
308 occur in web pages. Here we will use it to rewrite gitit's links so that
309 they all begin with `/wiki/`.
310
311 First, tell gitit not to compress pages, since `mod_proxy_html`
312 needs uncompressed pages to parse. You can do this by setting
313 the gitit configuration option
314
77d20a3 @jgm README changes: running with darcs, updated some refs to config options...
authored
315 compress-responses: no
316
317 Second, modify the link in the `reset-password-message` in the
318 configuration file: instead of
319
320 http://$hostname$:$port$$resetlink$
321
322 set it to
323
324 http://$hostname$/wiki$resetlink$
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
325
326 Restart gitit.
327
328 Now add the following lines to the apache configuration file for the
329 `mysite.com` server:
330
331 # These commands will proxy /wiki/ to port 5001
332
333 ProxyRequests Off
334
335 <Proxy *>
336 Order deny,allow
337 Allow from all
338 </Proxy>
339
340 ProxyPass /wiki/ http://127.0.0.1:5001/
341
342 <Location /wiki/>
343 SetOutputFilter proxy-html
344 ProxyPassReverse /
345 ProxyHTMLURLMap / /wiki/
346 RequestHeader unset Accept-Encoding
347 </Location>
348
349 Reload your apache configuration and you should be set.
350
351 For further information on the use of `mod_proxy_http` to rewrite URLs,
352 see the [`mod_proxy_html` guide].
353
354 [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
355
45a9c7f @jgm Reformatted README using standard markdown.
authored
356 Reporting bugs
357 ==============
89725fd @jgm Initial commit.
authored
358
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
359 Bugs may be reported (and feature requests filed) at
360 <http://code.google.com/p/gitit/issues/list>.
89725fd @jgm Initial commit.
authored
361
45a9c7f @jgm Reformatted README using standard markdown.
authored
362 Acknowledgements
363 ================
89725fd @jgm Initial commit.
authored
364
980a07b @jgm Fixed spelling of Gwern Branwen's name in README.
authored
365 Gwern Branwen helped to optimize Gitit. Simon Michael contributed the patch for
97e0043 Improved README.
John MacFarlane authored
366 RST support. Henry Laxen helped with the apache proxy instructions.
16f9dde @jgm Updated configuration section of README.
authored
367
5c5c337 @jgm Updated README.
authored
368 The visual layout is shamelessly borrowed from Wikipedia.
89725fd @jgm Initial commit.
authored
369
5c5c337 @jgm Updated README.
authored
370 The stylesheets are influenced by Wikipedia's stylesheets and by the
371 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
372 `img/icons` come from bluetrip as well.
373
Something went wrong with that request. Please try again.