Skip to content
Newer
Older
100644 352 lines (252 sloc) 12.2 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
89e0a04 @jgm Added note about possibility of putting static inside repository.
authored
159 Note: if you set `staticDir` to be a subdirectory of `repositoryPath`,
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
45a9c7f @jgm Reformatted README using standard markdown.
authored
165 Changing the theme
166 ------------------
89725fd @jgm Initial commit.
authored
167
97e0043 Improved README.
John MacFarlane authored
168 To change the look of the wiki, you can modify `screen.css` in
169 `static/css`. But a better approach is to add a line to `template.html`
170 that imports your own custom stylesheet. This line should go
171 after the line that links to `/css/screen.css`:
172
173 <link href="/css/my-screen.css" rel="stylesheet" media="screen, projection" type="text/css" />
174
175 Then add `my-screen.css` to the `static/css` directory and customize
176 it as you see fit. The advantage of this approach is that you won't
177 need to merge changes in `screen.css` when gitit is updated. You can
178 just copy the revised `screen.css` into your `static/css` directory.
179
5c5c337 @jgm Updated README.
authored
180 To change the look of printed pages, modify `print.css`.
97e0043 Improved README.
John MacFarlane authored
181
f498fc6 @jgm Use HStringTemplate template for pages.
authored
182 The logo picture can be changed by copying a new PNG file to
97e0043 Improved README.
John MacFarlane authored
183 `static/img/logo.png`.
184
185 For more radical changes, you can modify `template.html`.
186 Note that interpolated variables are surrounded by `$`s, so literal
187 `$` must be backslash-escaped.
89725fd @jgm Initial commit.
authored
188
45a9c7f @jgm Reformatted README using standard markdown.
authored
189 Adding support for math
190 -----------------------
89725fd @jgm Initial commit.
authored
191
45a9c7f @jgm Reformatted README using standard markdown.
authored
192 Gitit is designed to work with [jsMath][] to display LaTeX math in HTML.
193 Download `jsMath` and `jsMath Image Fonts` from the [jsMath download page][].
89725fd @jgm Initial commit.
authored
194 You'll have two `.zip` archives. Unzip them both in the
5c5c337 @jgm Updated README.
authored
195 `static/js` directory (a new subdirectory, `jsMath`, will be
89725fd @jgm Initial commit.
authored
196 created). You can test to see if math is working properly by clicking
197 "help" on the top navigation bar and looking for the math example
483e9fb @jgm Added explanatory note about jsMath to README.
authored
198 (the quadratic formula). Note that if you copied the `jsMath` directory
199 into `static` *after* starting gitit, you will have to restart gitit
200 for the change to be noticed. Gitit checks for the existence of the
201 jsMath files when it starts, and will not include links to them unless
202 they exist.
89725fd @jgm Initial commit.
authored
203
204 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
205
206 Here is a formula: $\frac{1}{\sqrt{c^2}}$
207
208 You can write display math by enclosing it in double dollar signs:
209
210 $$\frac{1}{\sqrt{c^2}}$$
211
212 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
213
45a9c7f @jgm Reformatted README using standard markdown.
authored
214 Highlighted source code
215 -----------------------
89725fd @jgm Initial commit.
authored
216
217 If gitit was compiled against a version of pandoc that has highlighting support
45a9c7f @jgm Reformatted README using standard markdown.
authored
218 (see above), you can get highlighted source code by using [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
219
220 ~~~ {.haskell .numberLines}
221 qsort [] = []
222 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
223 qsort (filter (>= x) xs)
224 ~~~
225
226 To see what languages are available:
227
228 pandoc -v
229
230 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
231
45a9c7f @jgm Reformatted README using standard markdown.
authored
232 Accessing the wiki via git
233 ==========================
89725fd @jgm Initial commit.
authored
234
235 All the pages and uploaded files are stored in a git repository. By default, this
236 lives in the `wikidata` directory (though this can be changed through configuration
237 options). So you can interact with the wiki using git command line tools:
238
239 git clone ssh://my.server.edu/path/of/wiki/wikidata
240 cd wikidata
241 vim Front\ Page.page # edit the page
242 git commit -m "Added message about wiki etiquette" Front\ Page.page
243 git push
244
245 If you now look at the Front Page on the wiki, you should see your changes
246 reflected there. Note that the pages all have the extension `.page`.
247
488e6bb README: Added instructions for proxying with apache.
John MacFarlane authored
248 Using gitit with apache
249 =======================
250
251 Most users who run a public-facing gitit will want gitit to appear
252 at a nice URL like `http://wiki.mysite.com` or
253 `http://mysite.com/wiki` rather than `http://mysite.com:5001`.
254 This can be achieved using apache's `mod_proxy`.
255
256 Proxying to `http://wiki.mysite.com`
257 ------------------------------------
258
259 Set up your DNS so that `http://wiki.mysite.com` maps to
260 your server's IP address. Make sure that the `mod_proxy` module is
261 loaded, and set up a virtual host with the following configuration:
262
263 <VirtualHost *>
264 ServerName wiki.mysite.com
265 DocumentRoot /var/www/
266 RewriteEngine On
267 ProxyPreserveHost On
268 ProxyRequests Off
269
270 <Proxy *>
271 Order deny,allow
272 Allow from all
273 </Proxy>
274
275 ProxyPassReverse / http://127.0.0.1:5001
276 RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]
277
278 ErrorLog /var/log/apache2/error.log
279 LogLevel warn
280
281 CustomLog /var/log/apache2/access.log combined
282 ServerSignature On
283
284 </VirtualHost>
285
286 Reload your apache configuration and you should be all set.
287
288 Proxying to `http://mysite.com/wiki`
289 ------------------------------------
290
291 Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`,
292 and `mod_proxy_html` modules are loaded. `mod_proxy_html`
293 is an external module, which can be obtained [here]
294 (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that
295 occur in web pages. Here we will use it to rewrite gitit's links so that
296 they all begin with `/wiki/`.
297
298 First, tell gitit not to compress pages, since `mod_proxy_html`
299 needs uncompressed pages to parse. You can do this by setting
300 the gitit configuration option
301
302 compressResponses: no
303
304 Restart gitit.
305
306 Now add the following lines to the apache configuration file for the
307 `mysite.com` server:
308
309 # These commands will proxy /wiki/ to port 5001
310
311 ProxyRequests Off
312
313 <Proxy *>
314 Order deny,allow
315 Allow from all
316 </Proxy>
317
318 ProxyPass /wiki/ http://127.0.0.1:5001/
319
320 <Location /wiki/>
321 SetOutputFilter proxy-html
322 ProxyPassReverse /
323 ProxyHTMLURLMap / /wiki/
324 RequestHeader unset Accept-Encoding
325 </Location>
326
327 Reload your apache configuration and you should be set.
328
329 For further information on the use of `mod_proxy_http` to rewrite URLs,
330 see the [`mod_proxy_html` guide].
331
332 [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html
333
45a9c7f @jgm Reformatted README using standard markdown.
authored
334 Reporting bugs
335 ==============
89725fd @jgm Initial commit.
authored
336
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
337 Bugs may be reported (and feature requests filed) at
338 <http://code.google.com/p/gitit/issues/list>.
89725fd @jgm Initial commit.
authored
339
45a9c7f @jgm Reformatted README using standard markdown.
authored
340 Acknowledgements
341 ================
89725fd @jgm Initial commit.
authored
342
980a07b @jgm Fixed spelling of Gwern Branwen's name in README.
authored
343 Gwern Branwen helped to optimize Gitit. Simon Michael contributed the patch for
97e0043 Improved README.
John MacFarlane authored
344 RST support. Henry Laxen helped with the apache proxy instructions.
16f9dde @jgm Updated configuration section of README.
authored
345
5c5c337 @jgm Updated README.
authored
346 The visual layout is shamelessly borrowed from Wikipedia.
89725fd @jgm Initial commit.
authored
347
5c5c337 @jgm Updated README.
authored
348 The stylesheets are influenced by Wikipedia's stylesheets and by the
349 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
350 `img/icons` come from bluetrip as well.
351
Something went wrong with that request. Please try again.