Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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