Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 447 lines (289 sloc) 14.579 kB
c787570 @mojombo readme driven development!
mojombo authored
1 gollum -- A wiki built on top of Git
2 ====================================
3
4 ## DESCRIPTION
5
8c09e26 @mojombo Revise description in readme.
mojombo authored
6 Gollum is a simple wiki system built on top of Git that powers GitHub Wikis.
c787570 @mojombo readme driven development!
mojombo authored
7
8c09e26 @mojombo Revise description in readme.
mojombo authored
8 Gollum wikis are simply Git repositories that adhere to a specific format.
9 Gollum pages may be written in a variety of formats and can be edited in a
10 number of ways depending on your needs. You can edit your wiki locally:
11
a1876cc Fixed formatting mistake (auto-wrap in vim)
Nathan Long authored
12 * With your favorite text editor or IDE (changes will be visible after committing).
8c09e26 @mojombo Revise description in readme.
mojombo authored
13 * With the built-in web interface.
14 * With the Gollum Ruby API.
8630676 @mojombo clarify the project description
mojombo authored
15
762608f @mojombo Improved readme.
mojombo authored
16 Gollum follows the rules of [Semantic Versioning](http://semver.org/) and uses
17 [TomDoc](http://tomdoc.org/) for inline documentation.
18
19
20 ## INSTALLATION
21
22 The best way to install Gollum is with RubyGems:
23
16d048c @mojombo Fix spelling error in readme.
mojombo authored
24 $ [sudo] gem install gollum
762608f @mojombo Improved readme.
mojombo authored
25
26 In order to use the various formats that Gollum supports, you will need to
27 separately install the necessary dependencies for each format. You only need
28 to install the dependencies for the formats that you plan to use.
29
30 * [ASCIIDoc](http://www.methods.co.nz/asciidoc/) -- `brew install asciidoc`
31 * [Creole](http://wikicreole.org/) -- `gem install creole`
32 * [Markdown](http://daringfireball.net/projects/markdown/) -- `gem install rdiscount`
33 * [Org](http://orgmode.org/) -- `gem install org-ruby`
34 * [Pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::HTML` comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
35 * [RDoc](http://rdoc.sourceforge.net/)
36 * [ReStructuredText](http://docutils.sourceforge.net/rst.html) -- `easy_install docutils`
37 * [Textile](http://www.textism.com/tools/textile/) -- `gem install RedCloth`
e1f92e3 @technoweenie update readme with new features
technoweenie authored
38 * [MediaWiki](http://www.mediawiki.org/wiki/Help:Formatting) -- `gem install wikicloth`
762608f @mojombo Improved readme.
mojombo authored
39
c787570 @mojombo readme driven development!
mojombo authored
40
7e94a80 @mojombo Document gollum executable in readme.
mojombo authored
41 ## RUNNING
42
43 To view and edit your Gollum repository locally via the built in web
44 interface, simply install the Gollum gem, navigate to your repository via the
45 command line, and run the executable:
46
47 $ gollum
48
49 This will start up a web server running the Gollum frontend and you can view
50 and edit your wiki at http://localhost:4567. To get help on the command line
51 utility, you can run it like so:
52
53 $ gollum --help
54
55
c787570 @mojombo readme driven development!
mojombo authored
56 ## REPO STRUCTURE
57
58 A Gollum repository's contents are designed to be human editable. Page content
59 is written in `page files` and may be organized into directories any way you
715758f @mojombo no layouts, just footers
mojombo authored
60 choose. Special footers can be created in `footer files`. Other content
61 (images, PDFs, etc) may also be present and organized in the same way.
6311f5d @mojombo allow layouts
mojombo authored
62
63
64 ## PAGE FILES
c787570 @mojombo readme driven development!
mojombo authored
65
eabab63 @mojombo use github-markup for conversions
mojombo authored
66 Page files may be written in any format supported by
45446f3 update the source code url of github markup
dblugeon authored
67 [GitHub-Markup](http://github.com/github/markup) (except roff). The
8ea176a @mojombo Remove roff support.
mojombo authored
68 current list of formats and allowed extensions is:
c787570 @mojombo readme driven development!
mojombo authored
69
04aa89a @mojombo Alphabetize formats and tell how to install them.
mojombo authored
70 * ASCIIDoc: .asciidoc
71 * Creole: .creole
72 * Markdown: .markdown, .mdown, .mkdn, .mkd, .md
73 * Org Mode: .org
74 * Pod: .pod
75 * RDoc: .rdoc
76 * ReStructuredText: .rest.txt, .rst.txt, .rest, .rst
77 * Textile: .textile
e1f92e3 @technoweenie update readme with new features
technoweenie authored
78 * MediaWiki: .mediawiki, .wiki
04aa89a @mojombo Alphabetize formats and tell how to install them.
mojombo authored
79
eabab63 @mojombo use github-markup for conversions
mojombo authored
80 Gollum detects the page file format via the extension, so files must have one
81 of the supported extensions in order to be converted.
c787570 @mojombo readme driven development!
mojombo authored
82
59d1ed3 @mojombo switch to endorse utf8 page names
mojombo authored
83 Page file names may contain any printable UTF-8 character except space
84 (U+0020) and forward slash (U+002F). If you commit a page file with any of
51960eb @mojombo revise page name spec
mojombo authored
85 these characters in the name it will not be accessible via the web interface.
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
86
c787570 @mojombo readme driven development!
mojombo authored
87 Even though page files may be placed in any directory, there is still only a
88 single namespace for page names, so all page files should have globally unique
aa2de6b @mojombo fix typos
mojombo authored
89 names regardless of where they are located in the repository.
c787570 @mojombo readme driven development!
mojombo authored
90
59d1ed3 @mojombo switch to endorse utf8 page names
mojombo authored
91 The special page file `Home.ext` (where the extension is one of the supported
6311f5d @mojombo allow layouts
mojombo authored
92 formats) will be used as the entrance page to your wiki. If it is missing, an
93 automatically generated table of contents will be shown instead.
94
e1f92e3 @technoweenie update readme with new features
technoweenie authored
95 ## SIDEBAR FILES
96
97 Sidebar files allow you to add a simple sidebar to your wiki. Sidebar files
98 are named `_Sidebar.ext` where the extension is one of the supported formats.
99 Sidebars affect all pages in their directory and any subdirectories that do not
100 have a sidebar file of their own.
6311f5d @mojombo allow layouts
mojombo authored
101
715758f @mojombo no layouts, just footers
mojombo authored
102 ## FOOTER FILES
6311f5d @mojombo allow layouts
mojombo authored
103
715758f @mojombo no layouts, just footers
mojombo authored
104 Footer files allow you to add a simple footer to your wiki. Footer files must
59d1ed3 @mojombo switch to endorse utf8 page names
mojombo authored
105 be named `_Footer.ext` where the extension is one of the supported formats.
e1f92e3 @technoweenie update readme with new features
technoweenie authored
106 Like sidebars, footers affect all pages in their directory and any
107 subdirectories that do not have a footer file of their own.
6311f5d @mojombo allow layouts
mojombo authored
108
c787570 @mojombo readme driven development!
mojombo authored
109
041be2b @mojombo html is sanitized
mojombo authored
110 ## HTML SANITIZATION
111
fb13144 @mojombo use gollum instead of github
mojombo authored
112 For security and compatibility reasons Gollum wikis may not contain custom CSS
188c90b @mojombo More docs on sanitization.
mojombo authored
113 or JavaScript. These tags will be stripped from the converted HTML. See
114 `docs/sanitization.md` for more details on what tags and attributes are
115 allowed.
041be2b @mojombo html is sanitized
mojombo authored
116
117
9d68c4e @mojombo Support external file links.
mojombo authored
118 ## BRACKET TAGS
119
120 A variety of Gollum tags use a double bracket syntax. For example:
121
122 [[Link]]
123
124 Some tags will accept attributes which are separated by pipe symbols. For
125 example:
126
127 [[Link|Page Title]]
128
129 In all cases, the first thing in the link is what is displayed on the page.
130 So, if the tag is an internal wiki link, the first thing in the tag will be
131 the link text displayed on the page. If the tag is an embedded image, the
132 first thing in the tag will be a path to an image file. Use this trick to
133 easily remember which order things should appear in tags.
134
e1f92e3 @technoweenie update readme with new features
technoweenie authored
135 Some formats, such as MediaWiki, support the opposite syntax:
136
137 [[Page Title|Link]]
9d68c4e @mojombo Support external file links.
mojombo authored
138
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
139 ## PAGE LINKS
c787570 @mojombo readme driven development!
mojombo authored
140
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
141 To link to another Gollum wiki page, use the Gollum Page Link Tag.
c787570 @mojombo readme driven development!
mojombo authored
142
9e3a307 @mojombo Small Readme clarification.
mojombo authored
143 [[Frodo Baggins]]
c787570 @mojombo readme driven development!
mojombo authored
144
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
145 The above tag will create a link to the corresponding page file named
9e3a307 @mojombo Small Readme clarification.
mojombo authored
146 `Frodo-Baggins.ext` where `ext` may be any of the allowed extension types. The
c787570 @mojombo readme driven development!
mojombo authored
147 conversion is as follows:
148
0b848d7 @mojombo Gollum.canonical_name -> Page.cname
mojombo authored
149 1. Replace any spaces (U+0020) with dashes (U+002D)
150 2. Replace any slashes (U+002F) with dashes (U+002D)
c787570 @mojombo readme driven development!
mojombo authored
151
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
152 If you'd like the link text to be something that doesn't map directly to the
153 page name, you can specify the actual page name after a pipe:
c787570 @mojombo readme driven development!
mojombo authored
154
51960eb @mojombo revise page name spec
mojombo authored
155 [[Frodo|Frodo Baggins]]
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
156
51960eb @mojombo revise page name spec
mojombo authored
157 The above tag will link to `Frodo-Baggins.ext` using "Frodo" as the link text.
c787570 @mojombo readme driven development!
mojombo authored
158
159 The page file may exist anywhere in the directory structure of the repository.
160 Gollum does a breadth first search and uses the first match that it finds.
161
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
162 Here are a few more examples:
163
8b2ab7a @mojombo lining up utf8 is hard
mojombo authored
164 [[J. R. R. Tolkien]] -> J.-R.-R.-Tolkien.ext
51960eb @mojombo revise page name spec
mojombo authored
165 [[Movies / The Hobbit]] -> Movies---The-Hobbit.ext
8b2ab7a @mojombo lining up utf8 is hard
mojombo authored
166 [[モルドール]] -> モルドール.ext
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
167
168
244d85d @mojombo Document external links in Readme.
mojombo authored
169 ## EXTERNAL LINKS
170
171 As a convenience, simple external links can be placed within brackets and they
172 will be linked to the given URL with the URL as the link text. For example:
173
174 [[http://example.com]]
175
176 External links must begin with either "http://" or "https://". If you need
177 something more flexible, you can resort to the link syntax in the page's
178 underlying markup format.
179
180
9d68c4e @mojombo Support external file links.
mojombo authored
181 ## ABSOLUTE VS. RELATIVE VS. EXTERNAL PATH
b3f6685 @mojombo explain absolute and relative paths
mojombo authored
182
183 For Gollum tags that operate on static files (images, PDFs, etc), the paths
9d68c4e @mojombo Support external file links.
mojombo authored
184 may be referenced as either relative, absolute, or external. Relative paths
185 point to a static file relative to the page file within the directory
186 structure of the Gollum repo (even though after conversion, all page files
187 appear to be top level). These paths are NOT prefixed with a slash. For
188 example:
b3f6685 @mojombo explain absolute and relative paths
mojombo authored
189
190 gollum.pdf
191 docs/diagram.png
192
193 Absolute paths point to a static file relative to the Gollum repo's
194 root, regardless of where the page file is stored within the directory
195 structure. These paths ARE prefixed with a slash. For example:
196
197 /pdfs/gollum.pdf
198 /docs/diagram.png
199
9d68c4e @mojombo Support external file links.
mojombo authored
200 External paths are full URLs. An external path must begin with either
201 "http://" or "https://". For example:
202
203 http://example.com/pdfs/gollum.pdf
204 http://example.com/images/diagram.png
205
b3f6685 @mojombo explain absolute and relative paths
mojombo authored
206 All of the examples in this README use relative paths, but you may use
207 whatever works best in your situation.
208
209
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
210 ## FILE LINKS
211
212 To link to static files that are contained in the Gollum repository you should
213 use the Gollum File Link Tag.
214
215 [[Gollum|gollum.pdf]]
216
9d68c4e @mojombo Support external file links.
mojombo authored
217 The first part of the tag is the link text. The path to the file appears after
218 the pipe.
d84d6a3 @mojombo clarify file tag
mojombo authored
219
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
220
007447d @mojombo image syntax
mojombo authored
221 ## IMAGES
222
223 To display images that are contained in the Gollum repository you should use
e1f92e3 @technoweenie update readme with new features
technoweenie authored
224 the Gollum Image Tag. This will display the actual image on the page.
007447d @mojombo image syntax
mojombo authored
225
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
226 [[gollum.png]]
007447d @mojombo image syntax
mojombo authored
227
228 In addition to the simple format, there are a variety of options that you
9d2ab0d @mojombo readme typos
mojombo authored
229 can specify between pipe delimiters.
007447d @mojombo image syntax
mojombo authored
230
231 To specify alt text, use the `alt=` option. Default is no alt text.
232
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
233 [[gollum.png|alt=Gollum and his precious wiki]]
007447d @mojombo image syntax
mojombo authored
234
235 To place the image in a frame, use the `frame` option. When combined with the
236 `alt=` option, the alt text will be used as a caption as well. Default is no
237 frame.
238
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
239 [[gollum.png|frame|alt=Gollum and his precious wiki]]
007447d @mojombo image syntax
mojombo authored
240
241 To specify the alignment of the image on the page, use the `align=` option.
4cec243 @mojombo get image tag attributes rollin
mojombo authored
242 Possible values are `left`, `center`, and `right`. Default is `left`.
007447d @mojombo image syntax
mojombo authored
243
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
244 [[gollum.png|align=center]]
007447d @mojombo image syntax
mojombo authored
245
4cec243 @mojombo get image tag attributes rollin
mojombo authored
246 To float an image so that text flows around it, use the `float` option. When
247 `float` is specified, only `left` and `right` are valid `align` options.
248 Default is not floating. When floating is activated but no alignment is
9d2ab0d @mojombo readme typos
mojombo authored
249 specified, default alignment is `left`.
007447d @mojombo image syntax
mojombo authored
250
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
251 [[gollum.png|float]]
007447d @mojombo image syntax
mojombo authored
252
253 To specify a max-width, use the `width=` option. Units must be specified in
076194a @mojombo There is no default width/height in reality.
mojombo authored
254 either `px` or `em`.
007447d @mojombo image syntax
mojombo authored
255
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
256 [[gollum.png|width=400px]]
007447d @mojombo image syntax
mojombo authored
257
258 To specify a max-height, use the `height=` option. Units must be specified in
076194a @mojombo There is no default width/height in reality.
mojombo authored
259 either `px` or `em`.
007447d @mojombo image syntax
mojombo authored
260
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
261 [[gollum.png|height=300px]]
c787570 @mojombo readme driven development!
mojombo authored
262
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
263 Any of these options may be composed together by simply separating them with
264 pipes.
c787570 @mojombo readme driven development!
mojombo authored
265
266
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
267 ## ESCAPING GOLLUM TAGS
c787570 @mojombo readme driven development!
mojombo authored
268
269 If you need the literal text of a wiki or static link to show up in your final
270 wiki page, simply preface the link with a single quote (like in LISP):
271
fe1f787 @mojombo use CW-style tags instead of Wikipedia-style tags
mojombo authored
272 '[[Page Link]]
273 '[[File Link|file.pdf]]
274 '[[image.jpg]]
c787570 @mojombo readme driven development!
mojombo authored
275
276 This is useful for writing about the link syntax in your wiki pages.
277
278
279 ## SYNTAX HIGHLIGHTING
280
2e2a79f @mojombo clarify syntax highlighting syntax
mojombo authored
281 In page files you can get automatic syntax highlighting for a wide range of
dda8a73 Clarified a couple of points in the documentation
Nathan Long authored
282 languages (courtesy of [Pygments](http://pygments.org/) - must install
283 separately) by using the following syntax:
c787570 @mojombo readme driven development!
mojombo authored
284
af7caae @mojombo refine the syntax highligting syntax
mojombo authored
285 ```ruby
cec610c @mojombo allow syntax hilighted code to be indented
mojombo authored
286 def foo
287 puts 'bar'
288 end
af7caae @mojombo refine the syntax highligting syntax
mojombo authored
289 ```
c787570 @mojombo readme driven development!
mojombo authored
290
291 The block must start with three backticks (as the first characters on the
292 line). After that comes the name of the language that is contained by the
293 block. The language must be one of the `short name` lexer strings supported by
294 Pygments. See the [list of lexers](http://pygments.org/docs/lexers/) for valid
af7caae @mojombo refine the syntax highligting syntax
mojombo authored
295 options.
cec610c @mojombo allow syntax hilighted code to be indented
mojombo authored
296
297 If the block contents are indented two spaces or one tab, then that whitespace
298 will be ignored (this makes the blocks easier to read in plaintext).
299
af7caae @mojombo refine the syntax highligting syntax
mojombo authored
300 The block must end with three backticks as the first characters on a
301 line.
c787570 @mojombo readme driven development!
mojombo authored
302
303
d37d575 @mojombo Support TeX-style math equations via MathJax.
mojombo authored
304 ## MATHEMATICAL EQUATIONS
305
306 Page files may contain mathematic equations in TeX syntax that will be nicely
307 typeset into the expected output. A block-style equation is delimited by `\[`
308 and `\]`. For example:
309
310 \[ P(E) = {n \choose k} p^k (1-p)^{ n-k} \]
311
312 Inline equations are delimited by `\(` and `\)`. These equations will appear
313 inline with regular text. For example:
314
68a370a @mojombo A few small fixes for the readme.
mojombo authored
315 The Pythagorean theorum is \( a^2 + b^2 = c^2 \).
d37d575 @mojombo Support TeX-style math equations via MathJax.
mojombo authored
316
317 Gollum uses [MathJax](http://www.mathjax.org/) to convert the TeX syntax into
318 output suitable for display in web browsers.
319
320
c787570 @mojombo readme driven development!
mojombo authored
321 ## API DOCUMENTATION
322
323 The Gollum API allows you to retrieve raw or formatted wiki content from a Git
324 repository, write new content to the repository, and collect various meta data
325 about the wiki as a whole.
326
327 Initialize the Gollum::Repo object:
328
329 # Require rubygems if necessary
330 require 'rubygems'
331
332 # Require the Gollum library
333 require 'gollum'
334
3ff1150 @mojombo start work on formatted_page
mojombo authored
335 # Create a new Gollum::Wiki object by initializing it with the path to the
c787570 @mojombo readme driven development!
mojombo authored
336 # Git repository.
6bb9d34 @mojombo gollum -> wiki in readme
mojombo authored
337 wiki = Gollum::Wiki.new("my-gollum-repo.git")
3ff1150 @mojombo start work on formatted_page
mojombo authored
338 # => <Gollum::Wiki>
c787570 @mojombo readme driven development!
mojombo authored
339
dddb736 @mojombo Minor readme typo and various whitespace fixups.
mojombo authored
340 By default, internal wiki links are all absolute from the root. To specify a different base path, you can specify the `:base_path` option:
baaa7c6 @mojombo Allow base path to be specified for wiki links.
mojombo authored
341
342 wiki = Gollum::Wiki.new("my-gollum-repo.git", :base_path => "/wiki")
343
c37204e @mojombo move formatted vs raw into Page
mojombo authored
344 Get the latest version of the given human or canonical page name:
c787570 @mojombo readme driven development!
mojombo authored
345
6bb9d34 @mojombo gollum -> wiki in readme
mojombo authored
346 page = wiki.page('page-name')
c787570 @mojombo readme driven development!
mojombo authored
347 # => <Gollum::Page>
348
c37204e @mojombo move formatted vs raw into Page
mojombo authored
349 page.raw_data
350 # => "# My wiki page"
351
352 page.formatted_data
c787570 @mojombo readme driven development!
mojombo authored
353 # => "<h1>My wiki page</h1>"
354
355 page.format
356 # => :markdown
357
358 vsn = page.version
9b412d2 @mojombo return Grit::Commit objects instead of Gollum::Version
mojombo authored
359 # => <Grit::Commit>
c787570 @mojombo readme driven development!
mojombo authored
360
361 vsn.id
362 # => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
363
aa7ae33 @mojombo Document Page#footer in Readme.
mojombo authored
364 Get the footer (if any) for a given page:
365
366 page.footer
367 # => <Gollum::Page>
368
61076b3 @mojombo implement Page#versions
mojombo authored
369 Get a list of versions for a given page:
c787570 @mojombo readme driven development!
mojombo authored
370
6bb9d34 @mojombo gollum -> wiki in readme
mojombo authored
371 vsns = wiki.page('page-name').versions
9b412d2 @mojombo return Grit::Commit objects instead of Gollum::Version
mojombo authored
372 # => [<Grit::Commit, <Grit::Commit, <Grit::Commit>]
c787570 @mojombo readme driven development!
mojombo authored
373
374 vsns.first.id
375 # => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
376
14b2913 @mojombo date -> authored_date
mojombo authored
377 vsns.first.authored_date
c787570 @mojombo readme driven development!
mojombo authored
378 # => Sun Mar 28 19:11:21 -0700 2010
379
380 Get a specific version of a given canonical page file:
381
6bb9d34 @mojombo gollum -> wiki in readme
mojombo authored
382 wiki.page('page-name', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
c787570 @mojombo readme driven development!
mojombo authored
383
384 Get the latest version of a given static file:
385
6bb9d34 @mojombo gollum -> wiki in readme
mojombo authored
386 file = wiki.file('asset.js')
c787570 @mojombo readme driven development!
mojombo authored
387 # => <Gollum::File>
388
9307900 @mojombo add Gollum::File
mojombo authored
389 file.raw_data
c787570 @mojombo readme driven development!
mojombo authored
390 # => "alert('hello');"
391
392 file.version
9307900 @mojombo add Gollum::File
mojombo authored
393 # => <Grit::Commit>
c787570 @mojombo readme driven development!
mojombo authored
394
395 Get a specific version of a given static file:
396
6bb9d34 @mojombo gollum -> wiki in readme
mojombo authored
397 wiki.file('asset.js', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
c787570 @mojombo readme driven development!
mojombo authored
398
206c8b0 @mojombo Implement Wiki#preview_page.
mojombo authored
399 Get an in-memory Page preview (useful for generating previews for web
400 interfaces):
401
402 preview = wiki.preview_page("My Page", "# Contents", :markdown)
403 preview.formatted_data
404 # => "<h1>Contents</h1>"
405
f4fea23 @mojombo clarify deletion docs
mojombo authored
406 Methods that write to the repository require a Hash of commit data that takes
407 the following form:
c787570 @mojombo readme driven development!
mojombo authored
408
9d743ba @mojombo implement Wiki#write_page
mojombo authored
409 commit = { :message => 'commit message',
410 :name => 'Tom Preston-Werner',
411 :email => 'tom@github.com' }
f4fea23 @mojombo clarify deletion docs
mojombo authored
412
413 Write a new version of a page (the file will be created if it does not already
414 exist) and commit the change. The file will be written at the repo root.
415
6bb9d34 @mojombo gollum -> wiki in readme
mojombo authored
416 wiki.write_page('Page Name', :markdown, 'Page contents', commit)
c787570 @mojombo readme driven development!
mojombo authored
417
90ba847 @mojombo Allow changine of format in Wiki#update_page.
mojombo authored
418 Update an existing page. If the format is different than the page's current
419 format, the file name will be changed to reflect the new format.
c787570 @mojombo readme driven development!
mojombo authored
420
5831f1d @technoweenie Wiki#find became Wiki#page at some point
technoweenie authored
421 page = wiki.page('Page Name')
760d9c1 @technoweenie Wiki#update_page takes a name parameter for renames
technoweenie authored
422 wiki.update_page(page, page.name, page.format, 'Page contents', commit)
c787570 @mojombo readme driven development!
mojombo authored
423
424 To delete a page and commit the change:
425
762608f @mojombo Improved readme.
mojombo authored
426 wiki.delete_page(page, commit)
427
428
68a370a @mojombo A few small fixes for the readme.
mojombo authored
429 ## CONTRIBUTE
762608f @mojombo Improved readme.
mojombo authored
430
431 If you'd like to hack on Gollum, start by forking my repo on GitHub:
432
46e0062 @mojombo A few tweaks to the contributors section of the readme.
mojombo authored
433 http://github.com/github/gollum
762608f @mojombo Improved readme.
mojombo authored
434
435 To get all of the dependencies, install the gem first. The best way to get
436 your changes merged back into core is as follows:
437
438 1. Clone down your fork
46e0062 @mojombo A few tweaks to the contributors section of the readme.
mojombo authored
439 1. Create a thoughtfully named topic branch to contain your change
762608f @mojombo Improved readme.
mojombo authored
440 1. Hack away
441 1. Add tests and make sure everything still passes by running `rake`
46e0062 @mojombo A few tweaks to the contributors section of the readme.
mojombo authored
442 1. If you are adding new functionality, document it in the README
762608f @mojombo Improved readme.
mojombo authored
443 1. Do not change the version number, I will do that on my end
444 1. If necessary, rebase your commits into logical chunks, without errors
445 1. Push the branch up to GitHub
e1f92e3 @technoweenie update readme with new features
technoweenie authored
446 1. Send a pull request to the github/gollum project.
Something went wrong with that request. Please try again.