Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 398 lines (287 sloc) 14.029 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
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
c332b94 @jgm Documentation changes for new index link format.
authored
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
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
141 Configuring gitit
142 =================
143
45a9c7f @jgm Reformatted README using standard markdown.
authored
144 Configuration options
145 ---------------------
89725fd @jgm Initial commit.
authored
146
147 You can set some configuration options when starting gitit, using the
ce07825 @jgm Added data/default.conf, which defines default config file values.
authored
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.
2859d1b @jgm Document --print-default-config.
authored
154
45a9c7f @jgm Reformatted README using standard markdown.
authored
155 The `static` directory
156 ----------------------
89725fd @jgm Initial commit.
authored
157
f8ab67e @jgm Reformatting (line lengths) of README.
authored
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.
89725fd @jgm Initial commit.
authored
164
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
165 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
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
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
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
45a9c7f @jgm Reformatted README using standard markdown.
authored
183 Changing the theme
184 ------------------
89725fd @jgm Initial commit.
authored
185
97e0043 Improved README.
John MacFarlane authored
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
5c5c337 @jgm Updated README.
authored
198 To change the look of printed pages, modify `print.css`.
97e0043 Improved README.
John MacFarlane authored
199
f498fc6 @jgm Use HStringTemplate template for pages.
authored
200 The logo picture can be changed by copying a new PNG file to
97e0043 Improved README.
John MacFarlane authored
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.
89725fd @jgm Initial commit.
authored
206
45a9c7f @jgm Reformatted README using standard markdown.
authored
207 Adding support for math
208 -----------------------
89725fd @jgm Initial commit.
authored
209
f8ab67e @jgm Reformatting (line lengths) of README.
authored
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.
89725fd @jgm Initial commit.
authored
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
45a9c7f @jgm Reformatted README using standard markdown.
authored
231 Highlighted source code
232 -----------------------
89725fd @jgm Initial commit.
authored
233
f8ab67e @jgm Reformatting (line lengths) of README.
authored
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][]:
89725fd @jgm Initial commit.
authored
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
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
250 Accessing the wiki via git or darcs
251 ===================================
89725fd @jgm Initial commit.
authored
252
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
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:
89725fd @jgm Initial commit.
authored
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
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
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
f8ab67e @jgm Reformatting (line lengths) of README.
authored
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
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
320
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
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$
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
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
e86d3dc @jgm Added note on using gitit as a library to README.
authored
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
45a9c7f @jgm Reformatted README using standard markdown.
authored
369 Reporting bugs
370 ==============
89725fd @jgm Initial commit.
authored
371
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
372 Bugs may be reported (and feature requests filed) at
373 <http://code.google.com/p/gitit/issues/list>.
89725fd @jgm Initial commit.
authored
374
45a9c7f @jgm Reformatted README using standard markdown.
authored
375 Acknowledgements
376 ================
89725fd @jgm Initial commit.
authored
377
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
378 A number of people have contributed patches:
379
8500b29 @jgm More contributors.
authored
380 - Gwern Branwen helped to optimize gitit and wrote the
381 InterwikiPlugin.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
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.
edeca79 More acknowledgements.
John MacFarlane authored
388 - Thomas Hartman helped improve the index page, making directory
389 browsing persistent.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
390 - Justin Bogner improved the appearance of the preview button.
8500b29 @jgm More contributors.
authored
391 - Kohei Ozaki contributed the ImgTexPlugin.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
392
393 Gitit's default visual layout is shamelessly borrowed from Wikipedia.
5c5c337 @jgm Updated README.
authored
394 The stylesheets are influenced by Wikipedia's stylesheets and by the
395 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
396 `img/icons` come from bluetrip as well.
397
Something went wrong with that request. Please try again.