Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 647 lines (471 sloc) 22.872 kB
45a9c7f @jgm Reformatted README using standard markdown.
authored
1 Gitit
2 =====
89725fd @jgm Initial commit.
authored
3
73336c2 @jgm README: use shortcut style markdown links.
authored
4 Gitit is a wiki program written in Haskell. It uses [Happstack] for
5 the web server and [pandoc] for markup processing. Pages and uploaded
6 files are stored in a [git], [darcs], or [mercurial] repository
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
7 and may be modified either by using the VCS's command-line tools or
8 through the wiki's web interface. By default, pandoc's extended version
9698018 @jgm Allow pages to be written in Org mode or DocBook syntax.
authored
9 of markdown is used as a markup language, but reStructuredText, LaTeX, HTML,
10 DocBook, or Emacs Org-mode markup can also be used. Pages can be exported in a
11 number of different formats, including LaTeX, RTF, OpenOffice ODT, and
12 MediaWiki markup. Gitit can be configured to display TeX math (using
73336c2 @jgm README: use shortcut style markdown links.
authored
13 [texmath]) and highlighted source code (using [highlighting-kate]).
89725fd @jgm Initial commit.
authored
14
0d14feb @jgm Added links to demo site in documentation and gitit.cabal.
authored
15 Other features include
16
17 * plugins: dynamically loaded page transformations written in Haskell
18 (see "Network.Gitit.Interface")
19
20 * categories
21
22 * TeX math
23
24 * syntax highlighting of source code files and code snippets (using
25 highlighting-kate)
26
27 * caching
28
29 * Atom feeds (site-wide and per-page)
30
31 * a library, "Network.Gitit", that makes it simple to include a gitit
32 wiki in any happstack application
33
34 You can see a running demo at <http://gitit.johnmacfarlane.net>.
35
f22d5c4 @jgm Changed default config to use-cache: no.
authored
36 [git]: http://git.or.cz
d9c8cd8 @jgm Modified description slightly, mentioning darcs as well as git.
authored
37 [darcs]: http://darcs.net
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
38 [mercurial]: http://mercurial.selenic.com/
89725fd @jgm Initial commit.
authored
39 [pandoc]: http://johnmacfarlane.net/pandoc
fd9eed5 @jgm Changed mentions of HAppS to Happstack.
authored
40 [Happstack]: http://happstack.com
f22d5c4 @jgm Changed default config to use-cache: no.
authored
41 [highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/
ff6f3b9 @jgm Updated math part of README.
authored
42 [texmath]: http://github.com/jgm/texmath/tree/master
89725fd @jgm Initial commit.
authored
43
45a9c7f @jgm Reformatted README using standard markdown.
authored
44 Getting started
45 ===============
89725fd @jgm Initial commit.
authored
46
45a9c7f @jgm Reformatted README using standard markdown.
authored
47 Compiling and installing gitit
48 ------------------------------
89725fd @jgm Initial commit.
authored
49
73336c2 @jgm README: use shortcut style markdown links.
authored
50 You'll need the [GHC] compiler and the [cabal-install] tool. GHC can
51 be downloaded [here]. Note that, starting with release 0.5, GHC 6.10
52 or higher is required. For [cabal-install] on *nix, follow the [quick
53 install] instructions.
89725fd @jgm Initial commit.
authored
54
55 [GHC]: http://www.haskell.org/ghc/
56 [here]: http://www.haskell.org/ghc/
484625a @cryptorick README: changed dead links
cryptorick authored
57 [cabal-install]: https://wiki.haskell.org/Cabal-Install
58 [quick install]: https://wiki.haskell.org/Cabal-Install#Unix
89725fd @jgm Initial commit.
authored
59
97e0043 Improved README.
John MacFarlane authored
60 Once you've got cabal-install, installing gitit is trivial:
89725fd @jgm Initial commit.
authored
61
a7c11fe @jgm Simplified installation instructions.
authored
62 cabal update
89725fd @jgm Initial commit.
authored
63 cabal install gitit
64
a7c11fe @jgm Simplified installation instructions.
authored
65 These commands will install the latest released version of gitit.
89725fd @jgm Initial commit.
authored
66 To install a version of gitit checked out from the repository,
67 change to the gitit directory and type:
68
69 cabal install
70
71 The `cabal` tool will automatically install all of the required haskell
72 libraries. If all goes well, by the end of this process, the latest
73 release of gitit will be installed in your local `.cabal` directory. You
74 can check this by trying:
75
76 gitit --version
77
78 If that doesn't work, check to see that `gitit` is in your local
79 cabal-install executable directory (usually `~/.cabal/bin`). And make
80 sure `~/.cabal/bin` is in your system path.
81
97e0043 Improved README.
John MacFarlane authored
82 Optional syntax highlighting support
83 ------------------------------------
84
85 If pandoc was compiled with optional syntax highlighting support,
86 this will be available in gitit too. This feature is recommended
87 if you plan to display source code on your wiki.
88
73336c2 @jgm README: use shortcut style markdown links.
authored
89 Highlighting support requires the [pcre] library, so make sure that
97e0043 Improved README.
John MacFarlane authored
90 is installed before continuing.
91
92 [pcre]: http://www.pcre.org/
93
94 To install gitit with highlighting support, first ensure that pandoc
95 is compiled with highlighting support, then install gitit as above:
96
97 cabal install pandoc -fhighlighting --reinstall
98 cabal install gitit
99
45a9c7f @jgm Reformatted README using standard markdown.
authored
100 Running gitit
101 -------------
89725fd @jgm Initial commit.
authored
102
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
103 To run gitit, you'll need `git` in your system path. (Or `darcs` or
104 `hg`, if you're using darcs or mercurial to store the wiki data.)
89725fd @jgm Initial commit.
authored
105
97e0043 Improved README.
John MacFarlane authored
106 Gitit assumes that the page files (stored in the git repository) are
107 encoded as UTF-8. Even page names may be UTF-8 if the file system
108 supports this. So you should make sure that you are using a UTF-8 locale
109 when running gitit. (To check this, type `locale`.)
73db5a1 @jgm Noted need for UTF-8 locale in README.
authored
110
f8ab67e @jgm Reformatting (line lengths) of README.
authored
111 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
112 directory where you have write access, since three directories, `static`,
113 `templates`, and `wikidata`, and two files, `gitit-users` and `gitit.log`,
114 will be created here. To start gitit, just type:
89725fd @jgm Initial commit.
authored
115
116 gitit
117
118 If all goes well, gitit will do the following:
119
120 1. Create a git repository, `wikidata`, and add a default front page.
d77f566 @jgm Updated README.markdown for changes to static and templates.
authored
121 2. Create a `static` directory containing files to be treated as
122 static files by gitit.
f1f023a @jgm Use nested templates in templates/ directory rather than template.html.
authored
123 3. Create a `templates` directory containing HStringTemplate templates
f498fc6 @jgm Use HStringTemplate template for pages.
authored
124 for wiki pages.
125 4. Start a web server on port 5001.
89725fd @jgm Initial commit.
authored
126
f8ab67e @jgm Reformatting (line lengths) of README.
authored
127 Check that it worked: open a web browser and go to
128 <http://localhost:5001>.
97e0043 Improved README.
John MacFarlane authored
129
bf28dcb README: added note about -p and -h options.
John MacFarlane authored
130 You can control the port that gitit runs on using the `-p` option:
6064190 @jgm Fixed markdown error in README.
authored
131 `gitit -p 4000` will start gitit on port 4000. Additional runtime
bf28dcb README: added note about -p and -h options.
John MacFarlane authored
132 options are described by `gitit -h`.
133
7fa7383 @jgm Updated README with information about metadata block.
authored
134 Using gitit
135 ===========
136
97e0043 Improved README.
John MacFarlane authored
137 Wiki links and formatting
138 -------------------------
139
140 For instructions on editing pages and creating links, see the "Help" page.
141
f8ab67e @jgm Reformatting (line lengths) of README.
authored
142 Gitit interprets links with empty URLs as wikilinks. Thus, in markdown
143 pages, `[Front Page]()` creates an internal wikilink to the page `Front
144 Page`. In reStructuredText pages, `` `Front Page <>`_ `` has the same
145 effect.
89725fd @jgm Initial commit.
authored
146
c332b94 @jgm Documentation changes for new index link format.
authored
147 If you want to link to a directory listing for a subdirectory, use a
148 trailing slash: `[foo/bar/]()` creates a link to the directory for
149 `foo/bar`.
150
7fa7383 @jgm Updated README with information about metadata block.
authored
151 Page metadata
152 -------------
153
154 Pages may optionally begin with a metadata block. Here is an example:
155
38209d9 @jgm Updated README with new metadata format.
authored
156 ---
157 format: latex+lhs
158 categories: haskell math
159 toc: no
160 title: Haskell and
7fa7383 @jgm Updated README with information about metadata block.
authored
161 Category Theory
38209d9 @jgm Updated README with new metadata format.
authored
162 ...
7fa7383 @jgm Updated README with information about metadata block.
authored
163
164 \section{Why Category Theory?}
165
d89590a @jgm Don't require blank line after metadata block.
authored
166 The metadata block consists of a list of key-value pairs, each on a
167 separate line. If needed, the value can be continued on one or more
168 additional line, which must begin with a space. (This is illustrated by
169 the "title" example above.) The metadata block must begin with a line
170 `---` and end with a line `...` optionally followed by one or more blank
171 lines. (The metadata block is a valid YAML document, though not all YAML
172 documents will be valid metadata blocks.)
7fa7383 @jgm Updated README with information about metadata block.
authored
173
174 Currently the following keys are supported:
175
176 format
177 : Overrides the default page type as specified in the configuration file.
178 Possible values are `markdown`, `rst`, `latex`, `html`, `markdown+lhs`,
179 `rst+lhs`, `latex+lhs`. (Capitalization is ignored, so you can also
180 use `LaTeX`, `HTML`, etc.) The `+lhs` variants indicate that the page
181 is to be interpreted as literate Haskell. If this field is missing,
182 the default page type will be used.
183
184 categories
185 : A space or comma separated list of categories to which the page belongs.
186
187 toc
188 : Overrides default setting for table-of-contents in the configuration file.
189 Values can be `yes`, `no`, `true`, or `false` (capitalization is ignored).
190
191 title
192 : By default the displayed page title is the page name. This metadata element
193 overrides that default.
194
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
195 Highlighted source code
196 -----------------------
197
198 If gitit was compiled against a version of pandoc that has highlighting
199 support (see above), you can get highlighted source code by using
73336c2 @jgm README: use shortcut style markdown links.
authored
200 [delimited code blocks]:
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
201
202 ~~~ {.haskell .numberLines}
203 qsort [] = []
204 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
205 qsort (filter (>= x) xs)
206 ~~~
207
4ff0a58 @jgm Small documentation improvement suggested by joee.
authored
208 To see what languages your pandoc was compiled to highlight:
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
209
210 pandoc -v
211
212 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
213
d77f566 @jgm Updated README.markdown for changes to static and templates.
authored
214 Configuring and customizing gitit
215 =================================
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
216
45a9c7f @jgm Reformatted README using standard markdown.
authored
217 Configuration options
218 ---------------------
89725fd @jgm Initial commit.
authored
219
fe77c93 README: Clarified use of -f option.
John MacFarlane authored
220 Use the option `-f [filename]` to specify a configuration file:
ce07825 @jgm Added data/default.conf, which defines default config file values.
authored
221
fe77c93 README: Clarified use of -f option.
John MacFarlane authored
222 gitit -f my.conf
223
97a1fd3 @ivuk Fix typos in README.markdown
ivuk authored
224 The configuration can be split between several files:
2e2a901 @freiric update documentation: configuration splitted inseveral files and gith…
freiric authored
225
e01c977 @freiric README: added missing -f in splitted configuration section
freiric authored
226 gitit -f my.conf -f additional.conf
2e2a901 @freiric update documentation: configuration splitted inseveral files and gith…
freiric authored
227
228 One use case is to keep sensible part of the configuration outside of a SCM
229 (oauth client secret for example).
230
fe77c93 README: Clarified use of -f option.
John MacFarlane authored
231 If this option is not used, gitit will use a default configuration.
232 To get a copy of the default configuration file, which you
233 can customize, just type:
234
235 gitit --print-default-config > my.conf
ce07825 @jgm Added data/default.conf, which defines default config file values.
authored
236
237 The default configuration file is documented with comments throughout.
2859d1b @jgm Document --print-default-config.
authored
238
45a9c7f @jgm Reformatted README using standard markdown.
authored
239 The `static` directory
240 ----------------------
89725fd @jgm Initial commit.
authored
241
d77f566 @jgm Updated README.markdown for changes to static and templates.
authored
242 On receiving a request, gitit always looks first in the `static`
243 directory (or in whatever directory is specified for `static-dir` in
244 the configuration file). If a file corresponding to the request is
245 found there, it is served immediately. If the file is not found in
246 `static`, gitit next looks in the `static` subdirectory of gitit's data
247 file (`$CABALDIR/share/gitit-x.y.z/data`). This is where default css,
248 images, and javascripts are stored. If the file is not found there
249 either, gitit treats the request as a request for a wiki page or wiki
250 command.
251
252 So, you can throw anything you want to be served statically (for
253 example, a `robots.txt` file or `favicon.ico`) in the `static`
254 directory. You can override any of gitit's default css, javascript, or
255 image files by putting a file with the same relative path in `static`.
2473f07 @jgm Added robots.txt to static.
authored
256 Note that gitit has a default `robots.txt` file that excludes all
257 URLs beginning with `/_`.
89725fd @jgm Initial commit.
authored
258
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
259 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
260 and then add the files in the static directory to your repository, you
261 can ensure that others who clone your wiki repository get these files
262 as well. It will not be possible to modify these files using the web
263 interface, but they will be modifiable via git.
264
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
265 Using a VCS other than git
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
266 --------------------------
267
268 By default, gitit will store wiki pages in a git repository in the
269 `wikidata` directory. If you'd prefer to use darcs instead of git,
270 you need to add the following field to the configuration file:
271
272 repository-type: Darcs
273
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
274 If you'd prefer to use mercurial, add:
275
276 repository-type: Mercurial
277
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
278 This program may be called "darcsit" instead of "gitit" when a darcs
279 backend is used.
280
99d1199 @jgm Added comments on filestore/maxcount to darcs sec of README.
authored
281 Note: we recommend that you use gitit/darcsit with darcs version
282 2.3.0 or greater. If you must use an older version of darcs, then
283 you need to compile the filestore library without the (default)
284 maxcount flag, before (re)installing gitit:
285
286 cabal install --reinstall filestore -f-maxcount
287 cabal install --reinstall gitit
288
289 Otherwise you will get an error when you attempt to access your
290 repository.
291
45a9c7f @jgm Reformatted README using standard markdown.
authored
292 Changing the theme
293 ------------------
89725fd @jgm Initial commit.
authored
294
d77f566 @jgm Updated README.markdown for changes to static and templates.
authored
295 To change the look of the wiki, you can modify `custom.css` in
296 `static/css`.
97e0043 Improved README.
John MacFarlane authored
297
d77f566 @jgm Updated README.markdown for changes to static and templates.
authored
298 To change the look of printed pages, copy gitit's default `print.css`
299 to `static/css` and modify it.
97e0043 Improved README.
John MacFarlane authored
300
f498fc6 @jgm Use HStringTemplate template for pages.
authored
301 The logo picture can be changed by copying a new PNG file to
ab55bfb @jgm Indicate size of default logo picture. Closes #291.
authored
302 `static/img/logo.png`. The default logo is 138x155 pixels.
97e0043 Improved README.
John MacFarlane authored
303
d77f566 @jgm Updated README.markdown for changes to static and templates.
authored
304 To change the footer, modify `templates/footer.st`.
305
306 For more radical changes, you can override any of the default
aeeb91e Templates are in data directory
Chris Eidhof authored
307 templates in `$CABALDIR/share/gitit-x.y.z/data/templates` by copying
21ad9ba @akerbos Changes to templates require a restart
akerbos authored
308 the file into `templates`, modifying it, and restarting gitit. The
309 `page.st` template is the master template; it includes the others.
310 Interpolated variables are surrounded by `$`s, so `literal $` must
311 be backslash-escaped.
89725fd @jgm Initial commit.
authored
312
45a9c7f @jgm Reformatted README using standard markdown.
authored
313 Adding support for math
314 -----------------------
89725fd @jgm Initial commit.
authored
315
7fa7383 @jgm Updated README with information about metadata block.
authored
316 To write math on a markdown-formatted wiki page, just enclose it
317 in dollar signs, as in LaTeX:
89725fd @jgm Initial commit.
authored
318
319 Here is a formula: $\frac{1}{\sqrt{c^2}}$
320
321 You can write display math by enclosing it in double dollar signs:
322
323 $$\frac{1}{\sqrt{c^2}}$$
324
ff6f3b9 @jgm Updated math part of README.
authored
325 Gitit can display TeX math in three different ways, depending on the
326 setting of `math` in the configuration file:
327
328 1. `mathml` (default): Math will be converted to MathML using
73336c2 @jgm README: use shortcut style markdown links.
authored
329 [texmath]. This method works with IE+mathplayer, Firefox, and
ff6f3b9 @jgm Updated math part of README.
authored
330 Opera, but not Safari.
331
73336c2 @jgm README: use shortcut style markdown links.
authored
332 2. `jsMath`: Math will be rendered using the [jsMath] javascript.
ff6f3b9 @jgm Updated math part of README.
authored
333 If you want to use this method, download `jsMath` and `jsMath
73336c2 @jgm README: use shortcut style markdown links.
authored
334 Image Fonts` from the [jsMath download page]. You'll have two
ff6f3b9 @jgm Updated math part of README.
authored
335 `.zip` archives. Unzip them both in the `static/js` directory (a new
336 subdirectory, `jsMath`, will be created). This works with all
337 browsers, but is slower and not as nice looking as MathML.
338
339 3. `raw`: Math will be rendered as raw LaTeX codes.
340
6a6388b @pvorb Fix some minor issues in README
pvorb authored
341 [jsMath]: http://www.math.union.edu/~dpvc/jsmath/
89725fd @jgm Initial commit.
authored
342 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
343
a9e422b @jgm Added a README section on restricting access. Closes #292.
authored
344 Restricting access
345 ------------------
346
347 If you want to limit account creation on your wiki, the easiest way to do this
348 is to provide an `access-question` in your configuration file. (See the commented
349 default configuration file.) Nobody will be able to create an account without
350 knowing the answer to the access question.
351
352 Another approach is to use HTTP authentication. (See the config file comments on
353 `authentication-method`.)
354
b874730 @freiric updated README for githulogin and comment in default config
freiric authored
355 Authentication through github
356 -----------------------------
357
358 If you want to authenticate the user from github through oauth2, you need to
359 register your app with github to obtain a OAuth client secret and add the
360 following section to your configuration file:
361
362 ```
363 [Github]
364 oauthclientid: 01239456789abcdef012
365 oauthclientsecret: 01239456789abcdef01239456789abcdef012394
366 oauthcallback: http://mysite/_githubCallback
367 oauthoauthorizeendpoint: https://github.com/login/oauth/authorize
368 oauthaccesstokenendpoint: https://github.com/login/oauth/access_token
b5fad47 @freiric README updated: github organization membership
freiric authored
369 ## Uncomment if you are checking membership against an organization and change
370 ## gitit-testorg to this organization:
371 # github-org: gitit-testorg
b874730 @freiric updated README for githulogin and comment in default config
freiric authored
372 ```
2e2a901 @freiric update documentation: configuration splitted inseveral files and gith…
freiric authored
373
374 The github authentication uses the scope `user:email`. This way, gitit gets the
375 email of the user, and the commit can be assigned to the right author if the
b5fad47 @freiric README updated: github organization membership
freiric authored
376 wikidata repository is pushed to github. Additionally, it uses `read:org` if you
377 uses the option `github-org` to check membership against an organization.
2e2a901 @freiric update documentation: configuration splitted inseveral files and gith…
freiric authored
378
379 To push your repository to gitub after each commit, you can add the file
380 `post-commit` with the content below in the .git/hooks directory of your
381 wikidata repository.
382
383 ```
384 #!/bin/sh
385 git push origin master 2>> logit
386 ```
b874730 @freiric updated README for githulogin and comment in default config
freiric authored
387
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
388 Plugins
389 =======
89725fd @jgm Initial commit.
authored
390
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
391 Plugins are small Haskell programs that transform a wiki page after it
9698018 @jgm Allow pages to be written in Org mode or DocBook syntax.
authored
392 has been converted from Markdown or another source format. See the example
393 plugins in the `plugins` directory. To enable a plugin, include the path to the
394 plugin (or its module name) in the `plugins` field of the configuration file.
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
395 (If the plugin name starts with `Network.Gitit.Plugin.`, gitit will assume that
396 the plugin is an installed module and will not look for a source file.)
89725fd @jgm Initial commit.
authored
397
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
398 Plugin support is enabled by default. However, plugin support makes
399 the gitit executable considerably larger and more memory-hungry.
400 If you don't need plugins, you may want to compile gitit without plugin
401 support. To do this, unset the `plugins` Cabal flag:
89725fd @jgm Initial commit.
authored
402
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
403 cabal install --reinstall gitit -f-plugins
89725fd @jgm Initial commit.
authored
404
e9ac5c2 @jgm Make plugins flag enabled by default.
authored
405 Note also that if you compile gitit for executable profiling, attempts
406 to load plugins will result in "internal error: PAP object entered!"
89725fd @jgm Initial commit.
authored
407
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
408 Accessing the wiki through git
409 ==============================
89725fd @jgm Initial commit.
authored
410
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
411 All the pages and uploaded files are stored in a git repository. By
412 default, this lives in the `wikidata` directory (though this can be
413 changed through configuration options). So you can interact with the
414 wiki using git command line tools:
89725fd @jgm Initial commit.
authored
415
416 git clone ssh://my.server.edu/path/of/wiki/wikidata
417 cd wikidata
418 vim Front\ Page.page # edit the page
419 git commit -m "Added message about wiki etiquette" Front\ Page.page
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
420 git push
89725fd @jgm Initial commit.
authored
421
422 If you now look at the Front Page on the wiki, you should see your changes
423 reflected there. Note that the pages all have the extension `.page`.
424
13b66f4 @jgm Added support for the new mercurial filestore backend.
authored
425 If you are using the darcs or mercurial backend, the commands will
426 be slightly different. See the documentation for your VCS for
427 details.
428
53fb6c2 @jgm Added notes on PDF caching and idle
authored
429 Performance
430 ===========
431
f22d5c4 @jgm Changed default config to use-cache: no.
authored
432 Caching
53fb6c2 @jgm Added notes on PDF caching and idle
authored
433 -------
f22d5c4 @jgm Changed default config to use-cache: no.
authored
434
435 By default, gitit does not cache content. If your wiki receives a lot of
436 traffic or contains pages that are slow to render, you may want to activate
437 caching. To do this, set the configuration option `use-cache` to `yes`.
53fb6c2 @jgm Added notes on PDF caching and idle
authored
438 By default, rendered pages, highlighted source files, and exported PDFs
439 will be cached in the `cache` directory. (Another directory can be
440 specified by setting the `cache-dir` configuration option.)
f22d5c4 @jgm Changed default config to use-cache: no.
authored
441
442 Cached pages are updated when pages are modified using the web
443 interface. They are not updated when pages are modified directly through
444 git or darcs. However, the cache can be refreshed manually by pressing
445 Ctrl-R when viewing a page, or by sending an HTTP GET or POST request to
446 `/_expire/path/to/page`, where `path/to/page` is the name of the page to
447 be expired.
448
449 Users who frequently update pages using git or darcs may wish to add a
450 hook to the repository that makes the appropriate HTTP request to expire
451 pages when they are updated. To facilitate such hooks, the gitit cabal
452 package includes an executable `expireGititCache`. Assuming you are
453 running gitit at port 5001 on localhost, and the environment variable
454 `CHANGED_FILES` contains a list of the files that have changed, you can
455 expire their cached versions using
456
457 expireGititCache http://localhost:5001 $CHANGED_FILES
458
459 Or you can specify the files directly:
460
461 expireGititCache http://localhost:5001 "Front Page.page" foo/bar/baz.c
462
463 This program will return a success status (0) if the page has been
464 successfully expired (or if it was never cached in the first place),
465 and a failure status (> 0) otherwise.
466
467 The cache is persistent through restarts of gitit. To expire all cached
468 pages, simply remove the `cache` directory.
469
53fb6c2 @jgm Added notes on PDF caching and idle
authored
470 Idle
471 ----
472
473 By default, GHC's runtime will repeatedly attempt to collect garbage
474 when an executable like Gitit is idle. This means that gitit will, after
475 the first page request, never use 0% CPU time and sleep, but will use
476 ~1%. This can be bad for battery life, among other things.
477
478 To fix this, one can disable the idle-time GC with the runtime flag
479 `-I0`:
480
481 gitit -f my.conf +RTS -I0 -RTS
482
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
483 Using gitit with apache
484 =======================
485
486 Most users who run a public-facing gitit will want gitit to appear
487 at a nice URL like `http://wiki.mysite.com` or
488 `http://mysite.com/wiki` rather than `http://mysite.com:5001`.
489 This can be achieved using apache's `mod_proxy`.
490
491 Proxying to `http://wiki.mysite.com`
492 ------------------------------------
493
494 Set up your DNS so that `http://wiki.mysite.com` maps to
ec6d6ba @petegallagher Update README.markdown
petegallagher authored
495 your server's IP address. Make sure that the `mod_proxy`, `mod_proxy_http` and `mod_rewrite` modules are
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
496 loaded, and set up a virtual host with the following configuration:
497
498 <VirtualHost *>
499 ServerName wiki.mysite.com
500 DocumentRoot /var/www/
501 RewriteEngine On
502 ProxyPreserveHost On
503 ProxyRequests Off
504
505 <Proxy *>
506 Order deny,allow
507 Allow from all
508 </Proxy>
509
510 ProxyPassReverse / http://127.0.0.1:5001
511 RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
512
513 ErrorLog /var/log/apache2/error.log
514 LogLevel warn
515
516 CustomLog /var/log/apache2/access.log combined
517 ServerSignature On
518
519 </VirtualHost>
520
521 Reload your apache configuration and you should be all set.
522
5690cd5 @fs111 added nginx example for proxy setup
fs111 authored
523 Using nginx to achieve the same
524 -------------------------------
8b14a55 @jgm Minor style edits to nginx instructions.
authored
525
526 Drop a file called `wiki.example.com.conf` into `/etc/nginx/conf.d`
527 (or where ever your distribution puts it).
5690cd5 @fs111 added nginx example for proxy setup
fs111 authored
528
529 server {
530 listen 80;
531 server_name wiki.example.com
532 location / {
533 proxy_pass http://127.0.0.1:5001/;
534 proxy_set_header X-Real-IP $remote_addr;
535 proxy_redirect off;
536 }
537 access_log /var/log/nginx/wiki.example.com.log main;
538 }
539
8b14a55 @jgm Minor style edits to nginx instructions.
authored
540 Reload your nginx config and you should be all set.
5690cd5 @fs111 added nginx example for proxy setup
fs111 authored
541
542
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
543 Proxying to `http://mysite.com/wiki`
544 ------------------------------------
545
546 Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
547 and `mod_proxy_html` modules are loaded. `mod_proxy_html`
548 is an external module, which can be obtained [here]
549 (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
550 occur in web pages. Here we will use it to rewrite gitit's links so that
551 they all begin with `/wiki/`.
552
f8ab67e @jgm Reformatting (line lengths) of README.
authored
553 First, tell gitit not to compress pages, since `mod_proxy_html` needs
554 uncompressed pages to parse. You can do this by setting the gitit
555 configuration option
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
556
77d20a3 @jgm README changes: running with darcs, updated some refs to config opti…
authored
557 compress-responses: no
558
559 Second, modify the link in the `reset-password-message` in the
560 configuration file: instead of
561
562 http://$hostname$:$port$$resetlink$
563
564 set it to
565
566 http://$hostname$/wiki$resetlink$
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
567
568 Restart gitit.
569
570 Now add the following lines to the apache configuration file for the
571 `mysite.com` server:
572
573 # These commands will proxy /wiki/ to port 5001
574
575 ProxyRequests Off
576
577 <Proxy *>
578 Order deny,allow
579 Allow from all
580 </Proxy>
581
582 ProxyPass /wiki/ http://127.0.0.1:5001/
583
584 <Location /wiki/>
585 SetOutputFilter proxy-html
586 ProxyPassReverse /
587 ProxyHTMLURLMap / /wiki/
8b04110 @wjv Document added mod_proxy_html setting in README
wjv authored
588 ProxyHTMLDocType "<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>" XHTML
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
589 RequestHeader unset Accept-Encoding
590 </Location>
591
592 Reload your apache configuration and you should be set.
593
594 For further information on the use of `mod_proxy_http` to rewrite URLs,
595 see the [`mod_proxy_html` guide].
596
597 [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
598
e86d3dc @jgm Added note on using gitit as a library to README.
authored
599 Using gitit as a library
600 ========================
601
602 By importing the module `Network.Gitit`, you can include a gitit wiki
603 (or several of them) in another happstack application. There are some
604 simple examples in the haddock documentation for `Network.Gitit`.
605
45a9c7f @jgm Reformatted README using standard markdown.
authored
606 Reporting bugs
607 ==============
89725fd @jgm Initial commit.
authored
608
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
609 Bugs may be reported (and feature requests filed) at
a9cfb74 @waldyrious update issues link
waldyrious authored
610 <https://github.com/jgm/gitit/issues>.
89725fd @jgm Initial commit.
authored
611
41595ee @jgm Added notice of mailing list to README.
authored
612 There is a mailing list for users and developers at
613 <http://groups.google.com/group/gitit-discuss>.
614
45a9c7f @jgm Reformatted README using standard markdown.
authored
615 Acknowledgements
616 ================
89725fd @jgm Initial commit.
authored
617
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
618 A number of people have contributed patches:
619
8500b29 @jgm More contributors.
authored
620 - Gwern Branwen helped to optimize gitit and wrote the
f22d5c4 @jgm Changed default config to use-cache: no.
authored
621 InterwikiPlugin. He also helped with the Feed module.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
622 - Simon Michael contributed the patch adding RST support.
623 - Henry Laxen added support for password resets and helped with
624 the apache proxy instructions.
625 - Anton van Straaten made the process of page generation
626 more modular by adding Gitit.ContentTransformer.
058ce02 @jgm Acknowledge Robin Green's patch in README.
authored
627 - Robin Green helped improve the plugin API and interface, and
628 fixed a security problem with the reset password code.
edeca79 More acknowledgements.
John MacFarlane authored
629 - Thomas Hartman helped improve the index page, making directory
312b9dc Added acknowledgements to README.
John MacFarlane authored
630 browsing persistent, and fixed a bug in template recompilation.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
631 - Justin Bogner improved the appearance of the preview button.
8500b29 @jgm More contributors.
authored
632 - Kohei Ozaki contributed the ImgTexPlugin.
312b9dc Added acknowledgements to README.
John MacFarlane authored
633 - Michael Terepeta improved validation of change descriptions.
cf6e15e @jgm Added acknowledgement for mightybyte.
authored
634 - mightybyte suggested making gitit available as a library,
635 and contributed a patch to ifLoggedIn that was needed to
636 make gitit usable with a custom authentication scheme.
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
637
b8bf081 @jgm Added thanks to darcs team in README.
authored
638 I am especially grateful to the darcs team for using darcsit for
639 their public-facing wiki. This has helped immensely in identifying
640 issues and improving performance.
641
bb8abc3 @jgm Improved acknowledgements, bringing list of contributors up to date.
authored
642 Gitit's default visual layout is shamelessly borrowed from Wikipedia.
5c5c337 @jgm Updated README.
authored
643 The stylesheets are influenced by Wikipedia's stylesheets and by the
644 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
645 `img/icons` come from bluetrip as well.
646
Something went wrong with that request. Please try again.