Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 267 lines (191 sloc) 9.968 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
41 cabal install pandoc -fhighlighting
42
43 You can skip this step if you don't care about highlighting support.
44
45 You can now install the latest release of gitit:
46
47 cabal update
48 cabal install gitit
49
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
75 a file, `gitit-users`, will be created here. To 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.
83 3. Start a web server on port 5001.
84
857efad @jgm Removed <> from URL in README.markdown.
authored
85 Check that it worked: open a web browser and go to http://localhost:5001.
89725fd @jgm Initial commit.
authored
86
45a9c7f @jgm Reformatted README using standard markdown.
authored
87 Configuration options
88 ---------------------
89725fd @jgm Initial commit.
authored
89
90 You can set some configuration options when starting gitit, using the
91 option `-f [filename]`. A configuration file takes the following form:
92
93 Config {
94 repositoryPath = "wikidata",
5c5c337 @jgm Updated README.
authored
95 userFile = "gitit-users",
89725fd @jgm Initial commit.
authored
96 staticDir = "static",
5c5c337 @jgm Updated README.
authored
97 wikiLogo = Just "/img/logo.png",
89725fd @jgm Initial commit.
authored
98 wikiTitle = "Wiki",
5c5c337 @jgm Updated README.
authored
99 wikiFooter = "Powered by Gitit\n<!-- Logo courtesy of http://flickr.com/photos/wolfhound/127936545/, licensed under Creative Commons Attribution license -->",
89725fd @jgm Initial commit.
authored
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
115 - `gitit-users` is a file containing user login information (with hashed
116 passwords). If it does not exist, gitit will start with an empty list
117 of users. Gitit will write a new `gitit-users` file on shutdown.
118
119 - `staticDir` is the (relative) path of a directory in which static content
120 (javascript, CSS, images) is stored. If it does not exist, gitit will
121 create it on startup.
122
123 - `wikiLogo` is either `Nothing` (no logo) or `Just "/url/of/logo"`.
124 By default, the logo is set to `/img/logo.png`, so the easiest way to
125 change the logo is just to copy a new file to `static/img/logo.png`.
126
127 - `wikiTitle` is the title that will be shown on the browser's title bar,
128 together with the name of the page being viewed.
129
130 - `wikiFooter` is raw HTML that will be inserted in the footer of every page.
131
132 - `tableOfContents` is either `False` or `True`. If it is `True`, a table
133 of contents (derived from the page's headers) will appear on each page.
134
135 - `maxUploadSize` (in bytes) sets a limit to the size of file uploads.
136
137 - `portNumber` is the number of the port on which the wiki will be served.
138
139 - `passwordSalt` is used to hash the passwords in the user database;
140 you should change this to something unique if you use gitit in a
141 production setting.
142
143 - `debugMode` is either `True` or `False`. If it is `True`, debug information
144 will be printed to the console when gitit is running.
145
146 - `frontPage` is the name of the page that is designated as the "front" or
147 "entrance" page of the wiki. Any page may be designated.
148
149 - `noEdit` is a list of pages that cannot be edited.
150
151 - `noDelete` is a list of pages that cannot be deleted.
152
153 - `accessQuestion` provides primitive access control. It is either `Nothing`,
154 in which case anyone will be allowed to create an account and edit wiki pages,
155 or `Just (question, [answer1, answer2, ...])`, where question is a prompt
156 that will be displayed when a user tries to create an account, and
157 `answer1, answer2, ...` are the valid responses. The user must provide a
158 valid response in order to create an account.
89725fd @jgm Initial commit.
authored
159
45a9c7f @jgm Reformatted README using standard markdown.
authored
160 Configuring gitit
161 =================
162
163 The `static` directory
164 ----------------------
89725fd @jgm Initial commit.
authored
165
166 If there is no wiki page or uploaded file corresponding to a request, gitit
167 always looks last in the `static` directory. So, for example, a file
5c5c337 @jgm Updated README.
authored
168 `foo.jpg` in the `img` subdirectory of the `static` directory will be
169 accessible at the url `/img/foo.jpg`. Pandoc creates three subdirectories
170 of `static`, `css`, `img`, and `js`, which include the icons, stylesheets,
171 and javascripts it uses.
89725fd @jgm Initial commit.
authored
172
45a9c7f @jgm Reformatted README using standard markdown.
authored
173 Changing the theme
174 ------------------
89725fd @jgm Initial commit.
authored
175
5c5c337 @jgm Updated README.
authored
176 To change the look of the wiki, modify `screen.css` in `static/css`.
177 To change the look of printed pages, modify `print.css`.
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
252 There is no bug tracker as yet, so report bugs directly to the author,
253 jgm at berkeley . edu
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.