Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 211 lines (153 sloc) 7.607 kb
45a9c7f @jgm Reformatted README using standard markdown.
authored
1 Gitit
2 =====
89725fd @jgm Initial commit.
authored
3
45a9c7f @jgm Reformatted README using standard markdown.
authored
4 Gitit is a wiki program written in Haskell. It uses [HAppS][] for the web
5 server and session state, [git][] for storage, history, search, diffs,
6 and merging, and [pandoc][] for markup processing. Pages can be added,
89725fd @jgm Initial commit.
authored
7 changed, and removed either on the web or using git's command-line
45a9c7f @jgm Reformatted README using standard markdown.
authored
8 tools. Gitit uses [pandoc][]'s extended version of markdown as its markup
89725fd @jgm Initial commit.
authored
9 language.
10
11 [git]: http://git.or.cz
12 [pandoc]: http://johnmacfarlane.net/pandoc
13 [HAppS]: http://happs.org
14
45a9c7f @jgm Reformatted README using standard markdown.
authored
15 Getting started
16 ===============
89725fd @jgm Initial commit.
authored
17
45a9c7f @jgm Reformatted README using standard markdown.
authored
18 Compiling and installing gitit
19 ------------------------------
89725fd @jgm Initial commit.
authored
20
45a9c7f @jgm Reformatted README using standard markdown.
authored
21 You'll need the [GHC][] compiler and the [cabal-install][] tool. GHC can
22 be downloaded [here][]. For [cabal-install][] on *nix, follow the [quick
23 install][] instructions.
89725fd @jgm Initial commit.
authored
24
25 [GHC]: http://www.haskell.org/ghc/
26 [here]: http://www.haskell.org/ghc/
27 [cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
28 [quick install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick Installation on Unix
29 [pcre]: http://www.pcre.org/
30
31 If you want the syntax highlighting feature, you need to make sure
32 that pandoc is compiled with support for it. First, make sure your system
45a9c7f @jgm Reformatted README using standard markdown.
authored
33 has the [pcre][] library installed. Then:
89725fd @jgm Initial commit.
authored
34
35 cabal install pandoc -fhighlighting
36
37 You can skip this step if you don't care about highlighting support.
38
39 You can now install the latest release of gitit:
40
41 cabal update
42 cabal install gitit
43
44 To install a version of gitit checked out from the repository,
45 change to the gitit directory and type:
46
47 cabal install
48
49 The `cabal` tool will automatically install all of the required haskell
50 libraries. If all goes well, by the end of this process, the latest
51 release of gitit will be installed in your local `.cabal` directory. You
52 can check this by trying:
53
54 gitit --version
55
56 If that doesn't work, check to see that `gitit` is in your local
57 cabal-install executable directory (usually `~/.cabal/bin`). And make
58 sure `~/.cabal/bin` is in your system path.
59
45a9c7f @jgm Reformatted README using standard markdown.
authored
60 Running gitit
61 -------------
89725fd @jgm Initial commit.
authored
62
45a9c7f @jgm Reformatted README using standard markdown.
authored
63 To run gitit, you'll need [git][] in your system path. Check this by doing
89725fd @jgm Initial commit.
authored
64
65 git --version
66
67 Switch to the directory where you want to run gitit. This should be a directory
68 where you have write access, since two directories, `static` and `wikidata`, will be
69 created here. To start gitit, just type:
70
71 gitit
72
73 If all goes well, gitit will do the following:
74
75 1. Create a git repository, `wikidata`, and add a default front page.
76 2. Create a `static` directory containing the scripts and CSS used by gitit.
77 3. Start a web server on port 5001.
78
857efad @jgm Removed <> from URL in README.markdown.
authored
79 Check that it worked: open a web browser and go to http://localhost:5001.
89725fd @jgm Initial commit.
authored
80
45a9c7f @jgm Reformatted README using standard markdown.
authored
81 Configuration options
82 ---------------------
89725fd @jgm Initial commit.
authored
83
84 You can set some configuration options when starting gitit, using the
85 option `-f [filename]`. A configuration file takes the following form:
86
87 Config {
88 repositoryPath = "wikidata",
89 staticDir = "static",
90 wikiBanner = "<img src=\"/images/bann.png\" alt=\"banner\"",
91 wikiTitle = "Wiki",
92 wikiFooter = "Powered by Gitit",
93 tableOfContents = False,
94 maxUploadSize = 100000,
95 portNumber = 5001,
96 passwordSalt = "l91snthoae8eou2340987",
650e9ec @jgm Added lockedPages config option; made Help a page.
authored
97 debugMode = True,
98 lockedPages = ["Help"],
89725fd @jgm Initial commit.
authored
99 accessQuestion = Just ("Enter the access code (to request a code, contact me@foo.bar.com):", ["abcd"])
100 }
101
102 For the most part, these options should be self-explanatory.
103
104 - The `wikiBanner` will be inserted before the top navigation bar on pages,
105 and can be used to include a banner or wiki title. It is raw HTML. Similarly,
106 the `wikiFooter` is raw HTML that will be inserted at the bottom of the page.
107 - The `tableOfContents` boolean determines whether a table of contents,
108 derived from the page's headers, will be included for every page.
109 - `maxUploadSize` (in bytes) limits the size of pages and uploads.
110 - The `passwordSalt` is used to encrypt passwords and should be
111 changed for every new site.
112 - `debugMode` causes diagnostic information to be printed to the console.
650e9ec @jgm Added lockedPages config option; made Help a page.
authored
113 - `lockedPages` is a list of pages that cannot be edited from the web interface.
114 (They may still be edited via git, by those with access to the repository.)
89725fd @jgm Initial commit.
authored
115 - The `accessQuestion` is either `Nothing` (in which case anyone will be
116 allowed to register for an account) or `Just (question, [ans1, ans2, ...])`
117 (in which case anyone who registers must first answer the `question` with
118 one of the provided answers). One can deter automated spammers by using
119 an `accessQuestion` with an easy and obvious answer. Or one can use an
120 `accessQuestion` to limit those who can edit a wiki to a trusted group.
121
45a9c7f @jgm Reformatted README using standard markdown.
authored
122 Configuring gitit
123 =================
124
125 The `static` directory
126 ----------------------
89725fd @jgm Initial commit.
authored
127
128 If there is no wiki page or uploaded file corresponding to a request, gitit
129 always looks last in the `static` directory. So, for example, a file
130 `foo.jpg` in the `images` subdirectory of the `static` directory will be
131 accessible at the url `/images/foo.jpg`. Pandoc creates two subdirectories
132 of `static`, `stylesheets` and `javascripts`, which include the CSS and
133 scripts it uses.
134
45a9c7f @jgm Reformatted README using standard markdown.
authored
135 Changing the theme
136 ------------------
89725fd @jgm Initial commit.
authored
137
138 To change the look of the wiki, modify `gitit.css` in `static/stylesheets`.
139
45a9c7f @jgm Reformatted README using standard markdown.
authored
140 Adding support for math
141 -----------------------
89725fd @jgm Initial commit.
authored
142
45a9c7f @jgm Reformatted README using standard markdown.
authored
143 Gitit is designed to work with [jsMath][] to display LaTeX math in HTML.
144 Download `jsMath` and `jsMath Image Fonts` from the [jsMath download page][].
89725fd @jgm Initial commit.
authored
145 You'll have two `.zip` archives. Unzip them both in the
146 `static/javascripts` directory (a new subdirectory, `jsMath`, will be
147 created). You can test to see if math is working properly by clicking
148 "help" on the top navigation bar and looking for the math example
149 (the quadratic formula).
150
151 To write math on a wiki page, just enclose it in dollar signs, as in LaTeX:
152
153 Here is a formula: $\frac{1}{\sqrt{c^2}}$
154
155 You can write display math by enclosing it in double dollar signs:
156
157 $$\frac{1}{\sqrt{c^2}}$$
158
159 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663
160 [jsMath]: http://www.math.union.edu/~dpvc/jsMath/
161
45a9c7f @jgm Reformatted README using standard markdown.
authored
162 Highlighted source code
163 -----------------------
89725fd @jgm Initial commit.
authored
164
165 If gitit was compiled against a version of pandoc that has highlighting support
45a9c7f @jgm Reformatted README using standard markdown.
authored
166 (see above), you can get highlighted source code by using [delimited code blocks][]:
89725fd @jgm Initial commit.
authored
167
168 ~~~ {.haskell .numberLines}
169 qsort [] = []
170 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
171 qsort (filter (>= x) xs)
172 ~~~
173
174 To see what languages are available:
175
176 pandoc -v
177
178 [delimited code blocks]: http://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks
179
45a9c7f @jgm Reformatted README using standard markdown.
authored
180 Accessing the wiki via git
181 ==========================
89725fd @jgm Initial commit.
authored
182
183 All the pages and uploaded files are stored in a git repository. By default, this
184 lives in the `wikidata` directory (though this can be changed through configuration
185 options). So you can interact with the wiki using git command line tools:
186
187 git clone ssh://my.server.edu/path/of/wiki/wikidata
188 cd wikidata
189 vim Front\ Page.page # edit the page
190 git commit -m "Added message about wiki etiquette" Front\ Page.page
191 git push
192
193 If you now look at the Front Page on the wiki, you should see your changes
194 reflected there. Note that the pages all have the extension `.page`.
195
45a9c7f @jgm Reformatted README using standard markdown.
authored
196 Reporting bugs
197 ==============
89725fd @jgm Initial commit.
authored
198
199 There is no bug tracker as yet, so report bugs directly to the author,
200 jgm at berkeley . edu
201
45a9c7f @jgm Reformatted README using standard markdown.
authored
202 Acknowledgements
203 ================
89725fd @jgm Initial commit.
authored
204
205 I borrowed some ideas about visual layout from Jeff Barczewski's fork
206 of Simon Rozet's `git-wiki`.
207
208 The code in `Gitit/State.hs` is based on http://hpaste.org/5957 by mightybyte,
209 as revised by dbpatterson.
210
Something went wrong with that request. Please try again.