Skip to content
This repository
Newer
Older
100644 310 lines (230 sloc) 12.159 kb
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
1 Gitit
2 =====
89725fd9 »
2008-11-06 Initial commit.
3
f8cd0519 »
2008-11-22 Updated README.
4 Gitit is a wiki program written in Haskell. It uses [HAppS][] for the
d9c8cd8b »
2009-01-24 Modified description slightly, mentioning darcs as well as git.
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.
16f9ddec »
2009-01-24 Updated configuration section of README.
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][]).
89725fd9 »
2008-11-06 Initial commit.
13
14 [git]: http://git.or.cz
d9c8cd8b »
2009-01-24 Modified description slightly, mentioning darcs as well as git.
15 [darcs]: http://darcs.net
89725fd9 »
2008-11-06 Initial commit.
16 [pandoc]: http://johnmacfarlane.net/pandoc
17 [HAppS]: http://happs.org
f8cd0519 »
2008-11-22 Updated README.
18 [jsMath]: http://www.math.union.edu/~dpvc/jsMath/
19 [highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/
89725fd9 »
2008-11-06 Initial commit.
20
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
21 Getting started
22 ===============
89725fd9 »
2008-11-06 Initial commit.
23
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
24 Compiling and installing gitit
25 ------------------------------
89725fd9 »
2008-11-06 Initial commit.
26
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
27 You'll need the [GHC][] compiler and the [cabal-install][] tool. GHC can
98adca8b »
2009-01-28 Note the GHC 6.10 requirement in README.
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
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
30 install][] instructions.
89725fd9 »
2008-11-06 Initial commit.
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 [pcre]: http://www.pcre.org/
37
38 If you want the syntax highlighting feature, you need to make sure
39 that pandoc is compiled with support for it. First, make sure your system
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
40 has the [pcre][] library installed. Then:
89725fd9 »
2008-11-06 Initial commit.
41
a7c11fe8 »
2008-11-30 Simplified installation instructions.
42 cabal update
43 cabal install -fhighlighting pandoc gitit
89725fd9 »
2008-11-06 Initial commit.
44
a7c11fe8 »
2008-11-30 Simplified installation instructions.
45 If you don't care about highlighting support, you can just do:
89725fd9 »
2008-11-06 Initial commit.
46
47 cabal install gitit
48
a7c11fe8 »
2008-11-30 Simplified installation instructions.
49 These commands will install the latest released version of gitit.
89725fd9 »
2008-11-06 Initial commit.
50 To install a version of gitit checked out from the repository,
51 change to the gitit directory and type:
52
53 cabal install
54
55 The `cabal` tool will automatically install all of the required haskell
56 libraries. If all goes well, by the end of this process, the latest
57 release of gitit will be installed in your local `.cabal` directory. You
58 can check this by trying:
59
60 gitit --version
61
62 If that doesn't work, check to see that `gitit` is in your local
63 cabal-install executable directory (usually `~/.cabal/bin`). And make
64 sure `~/.cabal/bin` is in your system path.
65
cdc73e59 »
2009-02-07 Make happstack the default.
66 Note: the build process is configured to use happstack by default.
67 If you want to use the old HAppS packages instead, use the flag
68 `-f-happstack`.
69
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
70 Running gitit
71 -------------
89725fd9 »
2008-11-06 Initial commit.
72
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
73 To run gitit, you'll need [git][] in your system path. Check this by doing
89725fd9 »
2008-11-06 Initial commit.
74
75 git --version
76
73db5a1f »
2009-01-28 Noted need for UTF-8 locale in README.
77 You should also make sure that you are using a UTF-8 locale.
78 (To check this, type `locale`.)
79
89725fd9 »
2008-11-06 Initial commit.
80 Switch to the directory where you want to run gitit. This should be a directory
5c5c3374 »
2008-11-22 Updated README.
81 where you have write access, since two directories, `static` and `wikidata`, and
f498fc6d »
2008-11-26 Use HStringTemplate template for pages.
82 two files, `gitit-users` and `template.html`, will be created here. To
83 start gitit, just type:
89725fd9 »
2008-11-06 Initial commit.
84
85 gitit
86
87 If all goes well, gitit will do the following:
88
89 1. Create a git repository, `wikidata`, and add a default front page.
90 2. Create a `static` directory containing the scripts and CSS used by gitit.
f498fc6d »
2008-11-26 Use HStringTemplate template for pages.
91 3. Create a `template.html` file containing an (HStringTemplate) template
92 for wiki pages.
93 4. Start a web server on port 5001.
89725fd9 »
2008-11-06 Initial commit.
94
857efadf »
2008-11-07 Removed <> from URL in README.markdown.
95 Check that it worked: open a web browser and go to http://localhost:5001.
89725fd9 »
2008-11-06 Initial commit.
96
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
97 Configuration options
98 ---------------------
89725fd9 »
2008-11-06 Initial commit.
99
100 You can set some configuration options when starting gitit, using the
101 option `-f [filename]`. A configuration file takes the following form:
102
103 Config {
16f9ddec »
2009-01-24 Updated configuration section of README.
104 repository = Git "wikidata",
105 defaultPageType = Markdown,
4dc907cd »
2008-12-31 Added recaptcha fields to configuration file.
106 userFile = "gitit-users",
107 templateFile = "template.html",
108 staticDir = "static",
109 tableOfContents = False,
110 maxUploadSize = 100000,
111 portNumber = 5001,
112 debugMode = True,
113 frontPage = "Front Page",
114 noEdit = ["Help", "Front Page"],
115 noDelete = ["Help", "Front Page"],
116 accessQuestion = Just ("Enter the access code (to request an access code, contact me@somewhere.org):", ["abcd"]),
117 useRecaptcha = False,
118 recaptchaPublicKey = "",
72c2cc05 »
2009-01-18 Better handling of mime types.
119 recaptchaPrivateKey = "",
bc068930 »
2009-02-08 Improvements to caching to limit memory use.
120 maxCacheSize = 2 * 1024 * 1024,
16f9ddec »
2009-01-24 Updated configuration section of README.
121 mimeTypesFile = "/etc/mime.types"
89725fd9 »
2008-11-06 Initial commit.
122 }
123
16f9ddec »
2009-01-24 Updated configuration section of README.
124 - `repository` specifies the type and (relative) path of the repository
125 in which the wiki's pages will be stored. If it does not exist, gitit
126 will create it on startup. Supported repository types are `Git` and
127 `Darcs`.
128
129 - `defaultPageType` is the type of markup used to interpret pages in
130 the wiki. Two values are currently supported: `Markdown` and `RST`.
131 If `Markdown` is selected, [pandoc]'s syntax extensions (for footnotes,
132 delimited code blocks, etc.) will be enabled. Note that pandoc's
133 reStructuredText parser is not complete, so some pages may
134 not be rendered correctly if `RST` is selected.
5c5c3374 »
2008-11-22 Updated README.
135
f498fc6d »
2008-11-26 Use HStringTemplate template for pages.
136 - `userFile` is a file containing user login information (with hashed
5c5c3374 »
2008-11-22 Updated README.
137 passwords). If it does not exist, gitit will start with an empty list
f498fc6d »
2008-11-26 Use HStringTemplate template for pages.
138 of users. Gitit will write a new `userFile` on shutdown.
139
140 - `templateFile` is a file containing an HTML template for the wiki pages.
141 If it does not exist, gitit will create a default template. (For most
142 purposes, this can be used just as it is, but some users may wish to
143 customize the look of their wiki.) `templateFile` is an
144 `HStringTemplate` template.
5c5c3374 »
2008-11-22 Updated README.
145
146 - `staticDir` is the (relative) path of a directory in which static content
147 (javascript, CSS, images) is stored. If it does not exist, gitit will
148 create it on startup.
149
150 - `tableOfContents` is either `False` or `True`. If it is `True`, a table
151 of contents (derived from the page's headers) will appear on each page.
152
153 - `maxUploadSize` (in bytes) sets a limit to the size of file uploads.
154
155 - `portNumber` is the number of the port on which the wiki will be served.
156
157 - `debugMode` is either `True` or `False`. If it is `True`, debug information
158 will be printed to the console when gitit is running.
159
160 - `frontPage` is the name of the page that is designated as the "front" or
161 "entrance" page of the wiki. Any page may be designated.
162
163 - `noEdit` is a list of pages that cannot be edited.
164
165 - `noDelete` is a list of pages that cannot be deleted.
166
167 - `accessQuestion` provides primitive access control. It is either `Nothing`,
168 in which case anyone will be allowed to create an account and edit wiki pages,
169 or `Just (question, [answer1, answer2, ...])`, where question is a prompt
170 that will be displayed when a user tries to create an account, and
171 `answer1, answer2, ...` are the valid responses. The user must provide a
172 valid response in order to create an account.
89725fd9 »
2008-11-06 Initial commit.
173
6e198d43 »
2008-12-31 Small tweaks on reCAPTCHA documentation in README.
174 - `useRecaptcha` is either `True` or `False`. It specifies whether to
175 use the [reCAPTCHA] service to provide captchas for user registration.
4dc907cd »
2008-12-31 Added recaptcha fields to configuration file.
176
6e198d43 »
2008-12-31 Small tweaks on reCAPTCHA documentation in README.
177 - `recaptchaPublicKey` and `recaptchaPrivateKey` are
178 [reCAPTCHA] keys, which can be obtained free of charge at
179 <http://recaptcha.net/api/getkey>. The values of these fields are ignored
180 if `useRecaptcha` is set to `False`.
4dc907cd »
2008-12-31 Added recaptcha fields to configuration file.
181
bc068930 »
2009-02-08 Improvements to caching to limit memory use.
182 - `maxCacheSize` is the maximum size of the in-memory page cache (in bytes).
183
72c2cc05 »
2009-01-18 Better handling of mime types.
184 - `mimeTypesFile` is the path of a file containing mime type associations.
185 Each line of the file should contain a mime type, followed by some space,
186 followed by a space-separated list of file extensions that map to that mime
187 type. If the file is not found, some simple defaults will be used.
188
4dc907cd »
2008-12-31 Added recaptcha fields to configuration file.
189 [reCAPTCHA]: http://recaptcha.net
190
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
191 Configuring gitit
192 =================
193
194 The `static` directory
195 ----------------------
89725fd9 »
2008-11-06 Initial commit.
196
197 If there is no wiki page or uploaded file corresponding to a request, gitit
198 always looks last in the `static` directory. So, for example, a file
5c5c3374 »
2008-11-22 Updated README.
199 `foo.jpg` in the `img` subdirectory of the `static` directory will be
200 accessible at the url `/img/foo.jpg`. Pandoc creates three subdirectories
201 of `static`, `css`, `img`, and `js`, which include the icons, stylesheets,
202 and javascripts it uses.
89725fd9 »
2008-11-06 Initial commit.
203
89e0a04b »
2009-01-16 Added note about possibility of putting static inside repository.
204 Note: if you set `staticDir` to be a subdirectory of `repositoryPath`,
205 and then add the files in the static directory to your repository, you
206 can ensure that others who clone your wiki repository get these files
207 as well. It will not be possible to modify these files using the web
208 interface, but they will be modifiable via git.
209
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
210 Changing the theme
211 ------------------
89725fd9 »
2008-11-06 Initial commit.
212
5c5c3374 »
2008-11-22 Updated README.
213 To change the look of the wiki, modify `screen.css` in `static/css`.
214 To change the look of printed pages, modify `print.css`.
f498fc6d »
2008-11-26 Use HStringTemplate template for pages.
215 The logo picture can be changed by copying a new PNG file to
216 `static/img/logo.png`. For more radical changes, one can modify
217 `template.html`.
89725fd9 »
2008-11-06 Initial commit.
218
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
219 Adding support for math
220 -----------------------
89725fd9 »
2008-11-06 Initial commit.
221
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
222 Gitit is designed to work with [jsMath][] to display LaTeX math in HTML.
223 Download `jsMath` and `jsMath Image Fonts` from the [jsMath download page][].
89725fd9 »
2008-11-06 Initial commit.
224 You'll have two `.zip` archives. Unzip them both in the
5c5c3374 »
2008-11-22 Updated README.
225 `static/js` directory (a new subdirectory, `jsMath`, will be
89725fd9 »
2008-11-06 Initial commit.
226 created). You can test to see if math is working properly by clicking
227 "help" on the top navigation bar and looking for the math example
483e9fb5 »
2009-02-01 Added explanatory note about jsMath to README.
228 (the quadratic formula). Note that if you copied the `jsMath` directory
229 into `static` *after* starting gitit, you will have to restart gitit
230 for the change to be noticed. Gitit checks for the existence of the
231 jsMath files when it starts, and will not include links to them unless
232 they exist.
89725fd9 »
2008-11-06 Initial commit.
233
234 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
235
236 Here is a formula: $\frac{1}{\sqrt{c^2}}$
237
238 You can write display math by enclosing it in double dollar signs:
239
240 $$\frac{1}{\sqrt{c^2}}$$
241
242 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
243
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
244 Highlighted source code
245 -----------------------
89725fd9 »
2008-11-06 Initial commit.
246
247 If gitit was compiled against a version of pandoc that has highlighting support
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
248 (see above), you can get highlighted source code by using [delimited code blocks][]:
89725fd9 »
2008-11-06 Initial commit.
249
250 ~~~ {.haskell .numberLines}
251 qsort [] = []
252 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
253 qsort (filter (>= x) xs)
254 ~~~
255
256 To see what languages are available:
257
258 pandoc -v
259
260 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
261
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
262 Accessing the wiki via git
263 ==========================
89725fd9 »
2008-11-06 Initial commit.
264
265 All the pages and uploaded files are stored in a git repository. By default, this
266 lives in the `wikidata` directory (though this can be changed through configuration
267 options). So you can interact with the wiki using git command line tools:
268
269 git clone ssh://my.server.edu/path/of/wiki/wikidata
270 cd wikidata
271 vim Front\ Page.page # edit the page
272 git commit -m "Added message about wiki etiquette" Front\ Page.page
273 git push
274
275 If you now look at the Front Page on the wiki, you should see your changes
276 reflected there. Note that the pages all have the extension `.page`.
277
5c5c3374 »
2008-11-22 Updated README.
278 Wiki links and formatting
279 =========================
280
281 For instructions on editing pages and creating links, see the "Help" page.
282
c118faad »
2009-01-24 Instructions on making wikilinks in mardkown and rst.
283 Gitit interprets links with empty URLs as wikilinks. Thus, in markdown pages,
284 `[Front Page]()` creates an internal wikilink to the page `Front Page`.
285 In reStructuredText pages, `` `Front Page <>`_ `` has the same effect.
286
a3c27c8f »
2008-12-30 Added note in README about using UTF-8.
287 Character encodings
288 ===================
289
290 Gitit assumes that the page files (stored in the git repository) are
ebbec6f2 »
2008-12-30 Added UTF-8 support.
291 encoded as UTF-8. Even page names may be UTF-8 if the file system supports
292 this. You should use a UTF-8 locale when running gitit.
a3c27c8f »
2008-12-30 Added note in README about using UTF-8.
293
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
294 Reporting bugs
295 ==============
89725fd9 »
2008-11-06 Initial commit.
296
a49ba22c »
2008-12-07 Added link to bug tracker on googlecode.
297 Bugs may be reported (and feature requests filed) at
298 <http://code.google.com/p/gitit/issues/list>.
89725fd9 »
2008-11-06 Initial commit.
299
45a9c7fb »
2008-11-07 Reformatted README using standard markdown.
300 Acknowledgements
301 ================
89725fd9 »
2008-11-06 Initial commit.
302
980a07b1 »
2009-01-30 Fixed spelling of Gwern Branwen's name in README.
303 Gwern Branwen helped to optimize Gitit. Simon Michael contributed the patch for
16f9ddec »
2009-01-24 Updated configuration section of README.
304 RST support.
305
5c5c3374 »
2008-11-22 Updated README.
306 The visual layout is shamelessly borrowed from Wikipedia.
89725fd9 »
2008-11-06 Initial commit.
307
5c5c3374 »
2008-11-22 Updated README.
308 The stylesheets are influenced by Wikipedia's stylesheets and by the
309 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
310 `img/icons` come from bluetrip as well.
311
Something went wrong with that request. Please try again.