Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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