Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 268 lines (192 sloc) 10.002 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`.
11477b2 @jgm Assume absolute URL for logo.
authored
126 Be sure to use an absolute URL.
5c5c337 @jgm Updated README.
authored
127
128 - `wikiTitle` is the title that will be shown on the browser's title bar,
129 together with the name of the page being viewed.
130
131 - `wikiFooter` is raw HTML that will be inserted in the footer of every page.
132
133 - `tableOfContents` is either `False` or `True`. If it is `True`, a table
134 of contents (derived from the page's headers) will appear on each page.
135
136 - `maxUploadSize` (in bytes) sets a limit to the size of file uploads.
137
138 - `portNumber` is the number of the port on which the wiki will be served.
139
140 - `passwordSalt` is used to hash the passwords in the user database;
141 you should change this to something unique if you use gitit in a
142 production setting.
143
144 - `debugMode` is either `True` or `False`. If it is `True`, debug information
145 will be printed to the console when gitit is running.
146
147 - `frontPage` is the name of the page that is designated as the "front" or
148 "entrance" page of the wiki. Any page may be designated.
149
150 - `noEdit` is a list of pages that cannot be edited.
151
152 - `noDelete` is a list of pages that cannot be deleted.
153
154 - `accessQuestion` provides primitive access control. It is either `Nothing`,
155 in which case anyone will be allowed to create an account and edit wiki pages,
156 or `Just (question, [answer1, answer2, ...])`, where question is a prompt
157 that will be displayed when a user tries to create an account, and
158 `answer1, answer2, ...` are the valid responses. The user must provide a
159 valid response in order to create an account.
89725fd @jgm Initial commit.
authored
160
45a9c7f @jgm Reformatted README using standard markdown.
authored
161 Configuring gitit
162 =================
163
164 The `static` directory
165 ----------------------
89725fd @jgm Initial commit.
authored
166
167 If there is no wiki page or uploaded file corresponding to a request, gitit
168 always looks last in the `static` directory. So, for example, a file
5c5c337 @jgm Updated README.
authored
169 `foo.jpg` in the `img` subdirectory of the `static` directory will be
170 accessible at the url `/img/foo.jpg`. Pandoc creates three subdirectories
171 of `static`, `css`, `img`, and `js`, which include the icons, stylesheets,
172 and javascripts it uses.
89725fd @jgm Initial commit.
authored
173
45a9c7f @jgm Reformatted README using standard markdown.
authored
174 Changing the theme
175 ------------------
89725fd @jgm Initial commit.
authored
176
5c5c337 @jgm Updated README.
authored
177 To change the look of the wiki, modify `screen.css` in `static/css`.
178 To change the look of printed pages, modify `print.css`.
89725fd @jgm Initial commit.
authored
179
45a9c7f @jgm Reformatted README using standard markdown.
authored
180 Adding support for math
181 -----------------------
89725fd @jgm Initial commit.
authored
182
45a9c7f @jgm Reformatted README using standard markdown.
authored
183 Gitit is designed to work with [jsMath][] to display LaTeX math in HTML.
184 Download `jsMath` and `jsMath Image Fonts` from the [jsMath download page][].
89725fd @jgm Initial commit.
authored
185 You'll have two `.zip` archives. Unzip them both in the
5c5c337 @jgm Updated README.
authored
186 `static/js` directory (a new subdirectory, `jsMath`, will be
89725fd @jgm Initial commit.
authored
187 created). You can test to see if math is working properly by clicking
188 "help" on the top navigation bar and looking for the math example
189 (the quadratic formula).
190
191 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
192
193 Here is a formula: $\frac{1}{\sqrt{c^2}}$
194
195 You can write display math by enclosing it in double dollar signs:
196
197 $$\frac{1}{\sqrt{c^2}}$$
198
199 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
200
45a9c7f @jgm Reformatted README using standard markdown.
authored
201 Highlighted source code
202 -----------------------
89725fd @jgm Initial commit.
authored
203
204 If gitit was compiled against a version of pandoc that has highlighting support
45a9c7f @jgm Reformatted README using standard markdown.
authored
205 (see above), you can get highlighted source code by using [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
206
207 ~~~ {.haskell .numberLines}
208 qsort [] = []
209 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
210 qsort (filter (>= x) xs)
211 ~~~
212
213 To see what languages are available:
214
215 pandoc -v
216
217 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
218
45a9c7f @jgm Reformatted README using standard markdown.
authored
219 Accessing the wiki via git
220 ==========================
89725fd @jgm Initial commit.
authored
221
222 All the pages and uploaded files are stored in a git repository. By default, this
223 lives in the `wikidata` directory (though this can be changed through configuration
224 options). So you can interact with the wiki using git command line tools:
225
226 git clone ssh://my.server.edu/path/of/wiki/wikidata
227 cd wikidata
228 vim Front\ Page.page # edit the page
229 git commit -m "Added message about wiki etiquette" Front\ Page.page
230 git push
231
232 If you now look at the Front Page on the wiki, you should see your changes
233 reflected there. Note that the pages all have the extension `.page`.
234
5c5c337 @jgm Updated README.
authored
235 Wiki links and formatting
236 =========================
237
238 For instructions on editing pages and creating links, see the "Help" page.
239
240 Upgrading and `_local`
241 ======================
242
243 HAppS uses the `_local` subdirectory to make state persistent.
244 Gitit does not rely on this persistence; the configuration and user database
245 are read from files on startup. So, it is okay to delete the `_local`
246 subdirectory. You may need to do this after you have upgraded to a new
247 version of gitit, with a different `AppState` data structure, because the
248 new gitit will not be able to read the old gitit's state.
249
45a9c7f @jgm Reformatted README using standard markdown.
authored
250 Reporting bugs
251 ==============
89725fd @jgm Initial commit.
authored
252
253 There is no bug tracker as yet, so report bugs directly to the author,
254 jgm at berkeley . edu
255
45a9c7f @jgm Reformatted README using standard markdown.
authored
256 Acknowledgements
257 ================
89725fd @jgm Initial commit.
authored
258
5c5c337 @jgm Updated README.
authored
259 The visual layout is shamelessly borrowed from Wikipedia.
89725fd @jgm Initial commit.
authored
260
261 The code in `Gitit/State.hs` is based on http://hpaste.org/5957 by mightybyte,
262 as revised by dbpatterson.
263
5c5c337 @jgm Updated README.
authored
264 The stylesheets are influenced by Wikipedia's stylesheets and by the
265 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in
266 `img/icons` come from bluetrip as well.
267
Something went wrong with that request. Please try again.