# jgm/gitit

 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 1 Gitit 2 ===== 89725fd Initial commit. jgm authored Nov 6, 2008 3 f8cd051 Updated README. jgm authored Nov 22, 2008 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 Initial commit. jgm authored Nov 7, 2008 14 15 [git]: http://git.or.cz 16 [pandoc]: http://johnmacfarlane.net/pandoc 17 [HAppS]: http://happs.org f8cd051 Updated README. jgm authored Nov 23, 2008 18 [jsMath]: http://www.math.union.edu/~dpvc/jsMath/ 19 [highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/ 89725fd Initial commit. jgm authored Nov 7, 2008 20 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 21 Getting started 22 =============== 89725fd Initial commit. jgm authored Nov 7, 2008 23 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 24 Compiling and installing gitit 25 ------------------------------ 89725fd Initial commit. jgm authored Nov 7, 2008 26 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 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 Initial commit. jgm authored Nov 7, 2008 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 Reformatted README using standard markdown. jgm authored Nov 7, 2008 39 has the [pcre][] library installed. Then: 89725fd Initial commit. jgm authored Nov 7, 2008 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 Reformatted README using standard markdown. jgm authored Nov 7, 2008 66 Running gitit 67 ------------- 89725fd Initial commit. jgm authored Nov 7, 2008 68 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 69 To run gitit, you'll need [git][] in your system path. Check this by doing 89725fd Initial commit. jgm authored Nov 7, 2008 70 71 git --version 72 73 Switch to the directory where you want to run gitit. This should be a directory 5c5c337 Updated README. jgm authored Nov 22, 2008 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 Initial commit. jgm authored Nov 7, 2008 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 Removed <> from URL in README.markdown. jgm authored Nov 7, 2008 85 Check that it worked: open a web browser and go to http://localhost:5001. 89725fd Initial commit. jgm authored Nov 7, 2008 86 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 87 Configuration options 88 --------------------- 89725fd Initial commit. jgm authored Nov 7, 2008 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 Updated README. jgm authored Nov 23, 2008 95 userFile = "gitit-users", 89725fd Initial commit. jgm authored Nov 7, 2008 96 staticDir = "static", 5c5c337 Updated README. jgm authored Nov 23, 2008 97 wikiLogo = Just "/img/logo.png", 89725fd Initial commit. jgm authored Nov 7, 2008 98 wikiTitle = "Wiki", 5c5c337 Updated README. jgm authored Nov 23, 2008 99 wikiFooter = "Powered by Gitit\n", 89725fd Initial commit. jgm authored Nov 7, 2008 100 tableOfContents = False, 101 maxUploadSize = 100000, 102 portNumber = 5001, 103 passwordSalt = "l91snthoae8eou2340987", 650e9ec Added lockedPages config option; made Help a page. jgm authored Nov 7, 2008 104 debugMode = True, 5c5c337 Updated README. jgm authored Nov 23, 2008 105 frontPage = "Front Page", 106 noEdit = ["Help", "Front Page"], ac9d40b Replaced lockedPages with noEdit and noDelete. jgm authored Nov 7, 2008 107 noDelete = ["Help", "Front Page"], 5c5c337 Updated README. jgm authored Nov 23, 2008 108 accessQuestion = Just ("Enter the access code (to request an access code, contact me@somewhere.org):", ["abcd"]) 89725fd Initial commit. jgm authored Nov 7, 2008 109 } 110 5c5c337 Updated README. jgm authored Nov 23, 2008 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 Initial commit. jgm authored Nov 7, 2008 159 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 160 Configuring gitit 161 ================= 162 163 The static directory 164 ---------------------- 89725fd Initial commit. jgm authored Nov 7, 2008 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 Updated README. jgm authored Nov 23, 2008 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 Initial commit. jgm authored Nov 7, 2008 172 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 173 Changing the theme 174 ------------------ 89725fd Initial commit. jgm authored Nov 7, 2008 175 5c5c337 Updated README. jgm authored Nov 23, 2008 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 Initial commit. jgm authored Nov 7, 2008 178 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 179 Adding support for math 180 ----------------------- 89725fd Initial commit. jgm authored Nov 7, 2008 181 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 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 Initial commit. jgm authored Nov 7, 2008 184 You'll have two .zip archives. Unzip them both in the 5c5c337 Updated README. jgm authored Nov 23, 2008 185 static/js directory (a new subdirectory, jsMath, will be 89725fd Initial commit. jgm authored Nov 7, 2008 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 Reformatted README using standard markdown. jgm authored Nov 7, 2008 200 Highlighted source code 201 ----------------------- 89725fd Initial commit. jgm authored Nov 7, 2008 202 203 If gitit was compiled against a version of pandoc that has highlighting support 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 204 (see above), you can get highlighted source code by using [delimited code blocks][]: 89725fd Initial commit. jgm authored Nov 7, 2008 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 Reformatted README using standard markdown. jgm authored Nov 7, 2008 218 Accessing the wiki via git 219 ========================== 89725fd Initial commit. jgm authored Nov 7, 2008 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 Updated README. jgm authored Nov 23, 2008 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 Reformatted README using standard markdown. jgm authored Nov 7, 2008 249 Reporting bugs 250 ============== 89725fd Initial commit. jgm authored Nov 7, 2008 251 252 There is no bug tracker as yet, so report bugs directly to the author, 253 jgm at berkeley . edu 254 45a9c7f Reformatted README using standard markdown. jgm authored Nov 7, 2008 255 Acknowledgements 256 ================ 89725fd Initial commit. jgm authored Nov 7, 2008 257 5c5c337 Updated README. jgm authored Nov 23, 2008 258 The visual layout is shamelessly borrowed from Wikipedia. 89725fd Initial commit. jgm authored Nov 7, 2008 259 260 The code in Gitit/State.hs is based on http://hpaste.org/5957 by mightybyte, 261 as revised by dbpatterson. 262 5c5c337 Updated README. jgm authored Nov 23, 2008 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