Skip to content
Newer
Older
100644 267 lines (194 sloc) 9.7 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
5 web server and session state, [git][] for storage, history, search,
6 diffs, and merging, and [pandoc][] for markup processing. Pages and
7 uploaded files are stored in a git repository and may be modified either
8 by using git's command-line tools or through the wiki's web interface.
9 Pandoc's extended version of markdown is used as a markup language.
10 Pages can be exported in a number of different formats, including LaTeX,
11 RTF, OpenOffice ODT, and MediaWiki markup. Gitit can be configured to
12 display TeX math (using [jsMath][]) and highlighted source code (using
13 [highlighting-kate][]).
89725fd @jgm Initial commit.
authored
14
15 [git]: http://git.or.cz
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 {
96 repositoryPath = "wikidata",
5c5c337 @jgm Updated README.
authored
97 userFile = "gitit-users",
f498fc6 @jgm Use HStringTemplate template for pages.
authored
98 templateFile = "template.html",
89725fd @jgm Initial commit.
authored
99 staticDir = "static",
100 tableOfContents = False,
101 maxUploadSize = 100000,
102 portNumber = 5001,
103 passwordSalt = "l91snthoae8eou2340987",
650e9ec @jgm Added lockedPages config option; made Help a page.
authored
104 debugMode = True,
5c5c337 @jgm Updated README.
authored
105 frontPage = "Front Page",
106 noEdit = ["Help", "Front Page"],
ac9d40b @jgm Replaced lockedPages with noEdit and noDelete.
authored
107 noDelete = ["Help", "Front Page"],
5c5c337 @jgm Updated README.
authored
108 accessQuestion = Just ("Enter the access code (to request an access code, contact me@somewhere.org):", ["abcd"])
89725fd @jgm Initial commit.
authored
109 }
110
5c5c337 @jgm Updated README.
authored
111 - `repositoryPath` is the (relative) path of the git repository in which
112 the wiki's pages will be stored. If it does not exist, gitit will create
113 it on startup.
114
f498fc6 @jgm Use HStringTemplate template for pages.
authored
115 - `userFile` is a file containing user login information (with hashed
5c5c337 @jgm Updated README.
authored
116 passwords). If it does not exist, gitit will start with an empty list
f498fc6 @jgm Use HStringTemplate template for pages.
authored
117 of users. Gitit will write a new `userFile` on shutdown.
118
119 - `templateFile` is a file containing an HTML template for the wiki pages.
120 If it does not exist, gitit will create a default template. (For most
121 purposes, this can be used just as it is, but some users may wish to
122 customize the look of their wiki.) `templateFile` is an
123 `HStringTemplate` template.
5c5c337 @jgm Updated README.
authored
124
125 - `staticDir` is the (relative) path of a directory in which static content
126 (javascript, CSS, images) is stored. If it does not exist, gitit will
127 create it on startup.
128
129 - `tableOfContents` is either `False` or `True`. If it is `True`, a table
130 of contents (derived from the page's headers) will appear on each page.
131
132 - `maxUploadSize` (in bytes) sets a limit to the size of file uploads.
133
134 - `portNumber` is the number of the port on which the wiki will be served.
135
136 - `passwordSalt` is used to hash the passwords in the user database;
137 you should change this to something unique if you use gitit in a
138 production setting.
139
140 - `debugMode` is either `True` or `False`. If it is `True`, debug information
141 will be printed to the console when gitit is running.
142
143 - `frontPage` is the name of the page that is designated as the "front" or
144 "entrance" page of the wiki. Any page may be designated.
145
146 - `noEdit` is a list of pages that cannot be edited.
147
148 - `noDelete` is a list of pages that cannot be deleted.
149
150 - `accessQuestion` provides primitive access control. It is either `Nothing`,
151 in which case anyone will be allowed to create an account and edit wiki pages,
152 or `Just (question, [answer1, answer2, ...])`, where question is a prompt
153 that will be displayed when a user tries to create an account, and
154 `answer1, answer2, ...` are the valid responses. The user must provide a
155 valid response in order to create an account.
89725fd @jgm Initial commit.
authored
156
45a9c7f @jgm Reformatted README using standard markdown.
authored
157 Configuring gitit
158 =================
159
160 The `static` directory
161 ----------------------
89725fd @jgm Initial commit.
authored
162
163 If there is no wiki page or uploaded file corresponding to a request, gitit
164 always looks last in the `static` directory. So, for example, a file
5c5c337 @jgm Updated README.
authored
165 `foo.jpg` in the `img` subdirectory of the `static` directory will be
166 accessible at the url `/img/foo.jpg`. Pandoc creates three subdirectories
167 of `static`, `css`, `img`, and `js`, which include the icons, stylesheets,
168 and javascripts it uses.
89725fd @jgm Initial commit.
authored
169
45a9c7f @jgm Reformatted README using standard markdown.
authored
170 Changing the theme
171 ------------------
89725fd @jgm Initial commit.
authored
172
5c5c337 @jgm Updated README.
authored
173 To change the look of the wiki, modify `screen.css` in `static/css`.
174 To change the look of printed pages, modify `print.css`.
f498fc6 @jgm Use HStringTemplate template for pages.
authored
175 The logo picture can be changed by copying a new PNG file to
176 `static/img/logo.png`. For more radical changes, one can modify
177 `template.html`.
89725fd @jgm Initial commit.
authored
178
45a9c7f @jgm Reformatted README using standard markdown.
authored
179 Adding support for math
180 -----------------------
89725fd @jgm Initial commit.
authored
181
45a9c7f @jgm Reformatted README using standard markdown.
authored
182 Gitit is designed to work with [jsMath][] to display LaTeX math in HTML.
183 Download `jsMath` and `jsMath Image Fonts` from the [jsMath download page][].
89725fd @jgm Initial commit.
authored
184 You'll have two `.zip` archives. Unzip them both in the
5c5c337 @jgm Updated README.
authored
185 `static/js` directory (a new subdirectory, `jsMath`, will be
89725fd @jgm Initial commit.
authored
186 created). You can test to see if math is working properly by clicking
187 "help" on the top navigation bar and looking for the math example
188 (the quadratic formula).
189
190 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
191
192 Here is a formula: $\frac{1}{\sqrt{c^2}}$
193
194 You can write display math by enclosing it in double dollar signs:
195
196 $$\frac{1}{\sqrt{c^2}}$$
197
198 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
199
45a9c7f @jgm Reformatted README using standard markdown.
authored
200 Highlighted source code
201 -----------------------
89725fd @jgm Initial commit.
authored
202
203 If gitit was compiled against a version of pandoc that has highlighting support
45a9c7f @jgm Reformatted README using standard markdown.
authored
204 (see above), you can get highlighted source code by using [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
205
206 ~~~ {.haskell .numberLines}
207 qsort [] = []
208 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
209 qsort (filter (>= x) xs)
210 ~~~
211
212 To see what languages are available:
213
214 pandoc -v
215
216 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
217
45a9c7f @jgm Reformatted README using standard markdown.
authored
218 Accessing the wiki via git
219 ==========================
89725fd @jgm Initial commit.
authored
220
221 All the pages and uploaded files are stored in a git repository. By default, this
222 lives in the `wikidata` directory (though this can be changed through configuration
223 options). So you can interact with the wiki using git command line tools:
224
225 git clone ssh://my.server.edu/path/of/wiki/wikidata
226 cd wikidata
227 vim Front\ Page.page # edit the page
228 git commit -m "Added message about wiki etiquette" Front\ Page.page
229 git push
230
231 If you now look at the Front Page on the wiki, you should see your changes
232 reflected there. Note that the pages all have the extension `.page`.
233
5c5c337 @jgm Updated README.
authored
234 Wiki links and formatting
235 =========================
236
237 For instructions on editing pages and creating links, see the "Help" page.
238
239 Upgrading and `_local`
240 ======================
241
242 HAppS uses the `_local` subdirectory to make state persistent.
243 Gitit does not rely on this persistence; the configuration and user database
244 are read from files on startup. So, it is okay to delete the `_local`
245 subdirectory. You may need to do this after you have upgraded to a new
246 version of gitit, with a different `AppState` data structure, because the
247 new gitit will not be able to read the old gitit's state.
248
45a9c7f @jgm Reformatted README using standard markdown.
authored
249 Reporting bugs
250 ==============
89725fd @jgm Initial commit.
authored
251
a49ba22 @jgm Added link to bug tracker on googlecode.
authored
252 Bugs may be reported (and feature requests filed) at
253 <http://code.google.com/p/gitit/issues/list>.
89725fd @jgm Initial commit.
authored
254
45a9c7f @jgm Reformatted README using standard markdown.
authored
255 Acknowledgements
256 ================
89725fd @jgm Initial commit.
authored
257
5c5c337 @jgm Updated README.
authored
258 The visual layout is shamelessly borrowed from Wikipedia.
89725fd @jgm Initial commit.
authored
259
260 The code in `Gitit/State.hs` is based on http://hpaste.org/5957 by mightybyte,
261 as revised by dbpatterson.
262
5c5c337 @jgm Updated README.
authored
263 The stylesheets are influenced by Wikipedia's stylesheets and by the
264 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
265 `img/icons` come from bluetrip as well.
266
Something went wrong with that request. Please try again.