Skip to content

HTTPS clone URL

Subversion checkout URL

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