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