Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 318 lines (234 sloc) 12.333 kb
45a9c7f @jgm Reformatted README using standard markdown.
authored
1 Gitit
2 =====
89725fd @jgm Initial commit.
authored
3
f8cd051 @jgm Updated README.
authored
4 Gitit is a wiki program written in Haskell. It uses [HAppS][] 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
17 [HAppS]: http://happs.org
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 [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
45a9c7f @jgm Reformatted README using standard markdown.
authored
40 has the [pcre][] library installed. Then:
89725fd @jgm Initial commit.
authored
41
a7c11fe @jgm Simplified installation instructions.
authored
42 cabal update
43 cabal install -fhighlighting pandoc gitit
89725fd @jgm Initial commit.
authored
44
a7c11fe @jgm Simplified installation instructions.
authored
45 If you don't care about highlighting support, you can just do:
89725fd @jgm Initial commit.
authored
46
47 cabal install gitit
48
a7c11fe @jgm Simplified installation instructions.
authored
49 These commands will install the latest released version of gitit.
89725fd @jgm Initial commit.
authored
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
cdc73e5 @jgm Make happstack the default.
authored
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
45a9c7f @jgm Reformatted README using standard markdown.
authored
70 Running gitit
71 -------------
89725fd @jgm Initial commit.
authored
72
45a9c7f @jgm Reformatted README using standard markdown.
authored
73 To run gitit, you'll need [git][] in your system path. Check this by doing
89725fd @jgm Initial commit.
authored
74
75 git --version
76
73db5a1 @jgm Noted need for UTF-8 locale in README.
authored
77 You should also make sure that you are using a UTF-8 locale.
78 (To check this, type `locale`.)
79
89725fd @jgm Initial commit.
authored
80 Switch to the directory where you want to run gitit. This should be a directory
5c5c337 @jgm Updated README.
authored
81 where you have write access, since two directories, `static` and `wikidata`, and
f498fc6 @jgm Use HStringTemplate template for pages.
authored
82 two files, `gitit-users` and `template.html`, will be created here. To
83 start gitit, just type:
89725fd @jgm Initial commit.
authored
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.
f498fc6 @jgm Use HStringTemplate template for pages.
authored
91 3. Create a `template.html` file containing an (HStringTemplate) template
92 for wiki pages.
93 4. Start a web server on port 5001.
89725fd @jgm Initial commit.
authored
94
857efad @jgm Removed <> from URL in README.markdown.
authored
95 Check that it worked: open a web browser and go to http://localhost:5001.
89725fd @jgm Initial commit.
authored
96
45a9c7f @jgm Reformatted README using standard markdown.
authored
97 Configuration options
98 ---------------------
89725fd @jgm Initial commit.
authored
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 {
16f9dde @jgm Updated configuration section of README.
authored
104 repository = Git "wikidata",
105 defaultPageType = Markdown,
4dc907c @jgm Added recaptcha fields to configuration file.
authored
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 = "",
72c2cc0 @jgm Better handling of mime types.
authored
119 recaptchaPrivateKey = "",
bc06893 @jgm Improvements to caching to limit memory use.
authored
120 maxCacheSize = 2 * 1024 * 1024,
16f9dde @jgm Updated configuration section of README.
authored
121 mimeTypesFile = "/etc/mime.types"
89725fd @jgm Initial commit.
authored
122 }
123
16f9dde @jgm Updated configuration section of README.
authored
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.
5c5c337 @jgm Updated README.
authored
135
f498fc6 @jgm Use HStringTemplate template for pages.
authored
136 - `userFile` is a file containing user login information (with hashed
5c5c337 @jgm Updated README.
authored
137 passwords). If it does not exist, gitit will start with an empty list
f498fc6 @jgm Use HStringTemplate template for pages.
authored
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.
5c5c337 @jgm Updated README.
authored
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.
89725fd @jgm Initial commit.
authored
173
6e198d4 @jgm Small tweaks on reCAPTCHA documentation in README.
authored
174 - `useRecaptcha` is either `True` or `False`. It specifies whether to
175 use the [reCAPTCHA] service to provide captchas for user registration.
4dc907c @jgm Added recaptcha fields to configuration file.
authored
176
6e198d4 @jgm Small tweaks on reCAPTCHA documentation in README.
authored
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`.
4dc907c @jgm Added recaptcha fields to configuration file.
authored
181
bc06893 @jgm Improvements to caching to limit memory use.
authored
182 - `maxCacheSize` is the maximum size of the in-memory page cache (in bytes).
183
72c2cc0 @jgm Better handling of mime types.
authored
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
4dc907c @jgm Added recaptcha fields to configuration file.
authored
189 [reCAPTCHA]: http://recaptcha.net
190
2859d1b @jgm Document --print-default-config.
authored
191 The easiest way to create a custom configuration file is to dump the default
192 configuration and modify it:
193
194 gitit --print-default-config > myconf.hs
195 # edit myconf.hs
196
45a9c7f @jgm Reformatted README using standard markdown.
authored
197 Configuring gitit
198 =================
199
200 The `static` directory
201 ----------------------
89725fd @jgm Initial commit.
authored
202
203 If there is no wiki page or uploaded file corresponding to a request, gitit
204 always looks last in the `static` directory. So, for example, a file
5c5c337 @jgm Updated README.
authored
205 `foo.jpg` in the `img` subdirectory of the `static` directory will be
206 accessible at the url `/img/foo.jpg`. Pandoc creates three subdirectories
207 of `static`, `css`, `img`, and `js`, which include the icons, stylesheets,
208 and javascripts it uses.
89725fd @jgm Initial commit.
authored
209
89e0a04 @jgm Added note about possibility of putting static inside repository.
authored
210 Note: if you set `staticDir` to be a subdirectory of `repositoryPath`,
211 and then add the files in the static directory to your repository, you
212 can ensure that others who clone your wiki repository get these files
213 as well. It will not be possible to modify these files using the web
214 interface, but they will be modifiable via git.
215
45a9c7f @jgm Reformatted README using standard markdown.
authored
216 Changing the theme
217 ------------------
89725fd @jgm Initial commit.
authored
218
5c5c337 @jgm Updated README.
authored
219 To change the look of the wiki, modify `screen.css` in `static/css`.
220 To change the look of printed pages, modify `print.css`.
f498fc6 @jgm Use HStringTemplate template for pages.
authored
221 The logo picture can be changed by copying a new PNG file to
222 `static/img/logo.png`. For more radical changes, one can modify
223 `template.html`.
89725fd @jgm Initial commit.
authored
224
45a9c7f @jgm Reformatted README using standard markdown.
authored
225 Adding support for math
226 -----------------------
89725fd @jgm Initial commit.
authored
227
45a9c7f @jgm Reformatted README using standard markdown.
authored
228 Gitit is designed to work with [jsMath][] to display LaTeX math in HTML.
229 Download `jsMath` and `jsMath Image Fonts` from the [jsMath download page][].
89725fd @jgm Initial commit.
authored
230 You'll have two `.zip` archives. Unzip them both in the
5c5c337 @jgm Updated README.
authored
231 `static/js` directory (a new subdirectory, `jsMath`, will be
89725fd @jgm Initial commit.
authored
232 created). You can test to see if math is working properly by clicking
233 "help" on the top navigation bar and looking for the math example
483e9fb @jgm Added explanatory note about jsMath to README.
authored
234 (the quadratic formula). Note that if you copied the `jsMath` directory
235 into `static` *after* starting gitit, you will have to restart gitit
236 for the change to be noticed. Gitit checks for the existence of the
237 jsMath files when it starts, and will not include links to them unless
238 they exist.
89725fd @jgm Initial commit.
authored
239
240 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
241
242 Here is a formula: $\frac{1}{\sqrt{c^2}}$
243
244 You can write display math by enclosing it in double dollar signs:
245
246 $$\frac{1}{\sqrt{c^2}}$$
247
248 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
249
45a9c7f @jgm Reformatted README using standard markdown.
authored
250 Highlighted source code
251 -----------------------
89725fd @jgm Initial commit.
authored
252
253 If gitit was compiled against a version of pandoc that has highlighting support
45a9c7f @jgm Reformatted README using standard markdown.
authored
254 (see above), you can get highlighted source code by using [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
255
256 ~~~ {.haskell .numberLines}
257 qsort [] = []
258 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
259 qsort (filter (>= x) xs)
260 ~~~
261
262 To see what languages are available:
263
264 pandoc -v
265
266 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
267
45a9c7f @jgm Reformatted README using standard markdown.
authored
268 Accessing the wiki via git
269 ==========================
89725fd @jgm Initial commit.
authored
270
271 All the pages and uploaded files are stored in a git repository. By default, this
272 lives in the `wikidata` directory (though this can be changed through configuration
273 options). So you can interact with the wiki using git command line tools:
274
275 git clone ssh://my.server.edu/path/of/wiki/wikidata
276 cd wikidata
277 vim Front\ Page.page # edit the page
278 git commit -m "Added message about wiki etiquette" Front\ Page.page
279 git push
280
281 If you now look at the Front Page on the wiki, you should see your changes
282 reflected there. Note that the pages all have the extension `.page`.
283
5c5c337 @jgm Updated README.
authored
284 Wiki links and formatting
285 =========================
286
287 For instructions on editing pages and creating links, see the "Help" page.
288
c118faa @jgm Instructions on making wikilinks in mardkown and rst.
authored
289 Gitit interprets links with empty URLs as wikilinks. Thus, in markdown pages,
290 `[Front Page]()` creates an internal wikilink to the page `Front Page`.
291 In reStructuredText pages, `` `Front Page <>`_ `` has the same effect.
292
a3c27c8 @jgm Added note in README about using UTF-8.
authored
293 Character encodings
294 ===================
295
296 Gitit assumes that the page files (stored in the git repository) are
ebbec6f @jgm Added UTF-8 support.
authored
297 encoded as UTF-8. Even page names may be UTF-8 if the file system supports
298 this. You should use a UTF-8 locale when running gitit.
a3c27c8 @jgm Added note in README about using UTF-8.
authored
299
45a9c7f @jgm Reformatted README using standard markdown.
authored
300 Reporting bugs
301 ==============
89725fd @jgm Initial commit.
authored
302
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
303 Bugs may be reported (and feature requests filed) at
304 <http://code.google.com/p/gitit/issues/list>.
89725fd @jgm Initial commit.
authored
305
45a9c7f @jgm Reformatted README using standard markdown.
authored
306 Acknowledgements
307 ================
89725fd @jgm Initial commit.
authored
308
980a07b @jgm Fixed spelling of Gwern Branwen's name in README.
authored
309 Gwern Branwen helped to optimize Gitit. Simon Michael contributed the patch for
16f9dde @jgm Updated configuration section of README.
authored
310 RST support.
311
5c5c337 @jgm Updated README.
authored
312 The visual layout is shamelessly borrowed from Wikipedia.
89725fd @jgm Initial commit.
authored
313
5c5c337 @jgm Updated README.
authored
314 The stylesheets are influenced by Wikipedia's stylesheets and by the
315 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
316 `img/icons` come from bluetrip as well.
317
Something went wrong with that request. Please try again.