File: README.md

package info (click to toggle)
ruby-gollum-lib 4.2.7.5-3~bpo9+1
  • links: PTS, VCS
  • area: main
  • in suites: stretch-backports
  • size: 396 kB
  • sloc: ruby: 2,560; makefile: 4
file content (266 lines) | stat: -rw-r--r-- 7,000 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
gollum lib -- A wiki built on top of Git [![build status](https://ci.gitlab.org/projects/7/status.png?ref=master)](https://ci.gitlab.org/projects/7?ref=master)
========================================

[![Gem Version](https://badge.fury.io/rb/gollum-lib.svg)](http://badge.fury.io/rb/gollum-lib)
[![Build Status](https://travis-ci.org/gollum/gollum-lib.svg?branch=master)](https://travis-ci.org/gollum/gollum-lib)
[![Dependency Status](https://gemnasium.com/gollum/gollum-lib.svg)](https://gemnasium.com/gollum/gollum-lib)

## DESCRIPTION

[Gollum](https://github.com/gollum/gollum) is a simple wiki system built on
top of Git that powers GitHub Wikis.

Gollum-lib is the Ruby API that allows you to retrieve raw or formatted wiki
content from a Git repository, write new content to the repository, and collect
various meta data about the wiki as a whole.

Gollum-lib follows the rules of [Semantic Versioning](http://semver.org/) and uses
[TomDoc](http://tomdoc.org/) for inline documentation.

## SYSTEM REQUIREMENTS

- Ruby 1.9.3+ (>2.0 recommended)
- Unix like operating system (OS X, Ubuntu, Debian, and more)
- Will not work on Windows with the default [grit](https://github.com/github/grit) adapter, but might work via JRuby (please let us know!)

## INSTALLATION

The best way to install Gollum-lib is with RubyGems:

```bash
$ [sudo] gem install gollum-lib
```

If you're installing from source, you can use [Bundler][bundler] to pick up all the
gems:

```bash
$ bundle install
```

In order to use the various formats that Gollum supports, you will need to
separately install the necessary dependencies for each format. You only need
to install the dependencies for the formats that you plan to use.

* [AsciiDoc](http://www.methods.co.nz/asciidoc/) -- `gem install asciidoctor`
* [Creole](http://wikicreole.org/) -- `gem install creole`
* [Markdown](http://daringfireball.net/projects/markdown/) -- `gem install redcarpet`
* [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown) -- `gem install github-markdown`
* [Org](http://orgmode.org/) -- `gem install org-ruby`
* [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.
* [RDoc](http://rdoc.sourceforge.net/)
* [ReStructuredText](http://docutils.sourceforge.net/rst.html) -- `easy_install docutils`
* [Textile](http://www.textism.com/tools/textile/) -- `gem install RedCloth`
* [MediaWiki](http://www.mediawiki.org/wiki/Help:Formatting) -- `gem install wikicloth`

[bundler]: http://gembundler.com/

## SYNTAX

Gollum supports a variety of formats and extensions (Markdown, MediaWiki, Textile, …).
On top of these formats Gollum lets you insert headers, footers, links, image, math and more.

Check out the [Gollum Wiki](https://github.com/gollum/gollum/wiki) for all of Gollum's formats and syntactic options.

## API DOCUMENTATION

Initialize the `Gollum::Repo` object:

```ruby
# Require rubygems if necessary
require 'rubygems'

# Require the Gollum library
require 'gollum-lib'

# Create a new Gollum::Wiki object by initializing it with the path to the
# Git repository.
wiki = Gollum::Wiki.new("my-gollum-repo.git")
# => <Gollum::Wiki>
```

By default, internal wiki links are all absolute from the root. To specify a different
base path, you can specify the `:base_path` option:

```ruby
wiki = Gollum::Wiki.new("my-gollum-repo.git", :base_path => "/wiki")
```

Note that `base_path` just modifies the links.

Get the latest version of the given human or canonical page name:

```ruby
page = wiki.page('page-name')
# => <Gollum::Page>

page.raw_data
# => "# My wiki page"

page.formatted_data
# => "<h1>My wiki page</h1>"

page.format
# => :markdown

vsn = page.version
# => <Gollum::Git::Commit>

vsn.id
# => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
```

Get the footer (if any) for a given page:

```ruby
page.footer
# => <Gollum::Page>
```

Get the header (if any) for a given page:

```ruby
page.header
# => <Gollum::Page>
```

Get a list of versions for a given page:

```ruby
vsns = wiki.page('page-name').versions
# => [<Gollum::Git::Commit, <Gollum::Git::Commit, <Gollum::Git::Commit>]

vsns.first.id
# => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'

vsns.first.authored_date
# => Sun Mar 28 19:11:21 -0700 2010
```

Get a specific version of a given canonical page file:

```ruby
wiki.page('page-name', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
```

Get the latest version of a given static file:

```ruby
file = wiki.file('asset.js')
# => <Gollum::File>

file.raw_data
# => "alert('hello');"

file.version
# => <Gollum::Git::Commit>
```

Get a specific version of a given static file:

```ruby
wiki.file('asset.js', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
```

Get an in-memory Page preview (useful for generating previews for web
interfaces):

```ruby
preview = wiki.preview_page("My Page", "# Contents", :markdown)
preview.formatted_data
# => "<h1>Contents</h1>"
```

Methods that write to the repository require a Hash of commit data that takes
the following form:

```ruby
commit = { :message => 'commit message',
           :name => 'Tom Preston-Werner',
           :email => 'tom@github.com' }
```

Write a new version of a page (the file will be created if it does not already
exist) and commit the change. The file will be written at the repo root.

```ruby
wiki.write_page('Page Name', :markdown, 'Page contents', commit)
```

Update an existing page. If the format is different than the page's current
format, the file name will be changed to reflect the new format.

```ruby
page = wiki.page('Page Name')
wiki.update_page(page, page.name, page.format, 'Page contents', commit)
```

To delete a page and commit the change:

```ruby
wiki.delete_page(page, commit)
```

Register or unregister a hook to be called after a page commit:

```ruby
Gollum::Hook.register(:post_commit, :hook_id) do |committer, sha1|
  # Your code here
end

Gollum::Hook.unregister(:post_commit, :hook_id)
```

## WINDOWS FILENAME VALIDATION

Note that filenames on windows must not contain any of the following characters `\ / : * ? " < > |`. See [this support article](http://support.microsoft.com/kb/177506) for details.

## RELEASING

Gollum-lib uses [Semantic Versioning](http://semver.org/). Having `x.y.z` :

For z releases:

```bash
$ rake bump
$ rake release
```

For x.y releases:

```bash
$ rake gemspec
$ rake release
```

## BUILDING THE GEM FROM MASTER

```bash
$ gem uninstall -aIx gollum-lib
$ git clone https://github.com/gollum/gollum-lib.git
$ cd gollum-lib
gollum-lib$ rake build
gollum-lib$ rake install
```

## RUN THE TESTS

```bash
$ bundle install
$ bundle exec rake test
```

## WORK WITH TEST REPOS

An example of how to add a test file to the bare repository `lotr.git`.

```bash
$ mkdir tmp; cd tmp
$ git clone ../lotr.git/ .
Cloning into '.'...
done.
$ git log
$ echo "test" > test.md
$ git add . ; git commit -am "Add test"
$ git push ../lotr.git/ master
```