Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Showing 1 changed file with 227 additions and 0 deletions. Show diff stats Hide diff stats

  1. 227  README.md
227  README.md
Source Rendered
... ...
@@ -0,0 +1,227 @@
  1
+gollum -- A wiki built on top of Git
  2
+====================================
  3
+
  4
+## DESCRIPTION
  5
+
  6
+Gollum is a simple wiki that uses Git for storage and revision histories. It
  7
+is designed so that you can create a compliant Git repository (known as a
  8
+Gollum repository) either by hand, by calling API methods, or via the web
  9
+interface.
  10
+
  11
+
  12
+## REPO STRUCTURE
  13
+
  14
+A Gollum repository's contents are designed to be human editable. Page content
  15
+is written in `page files` and may be organized into directories any way you
  16
+choose. Other content (images, CSS, JavaScript, PDFs, etc) may also be
  17
+present and organized in the same way.
  18
+
  19
+Page files may be written in formats that render to HTML. Currently supported
  20
+formats are Markdown, Textile, and HTML. They must have the proper file
  21
+extension that corresponds to the format of the content:
  22
+
  23
+  * Markdown: .markdown, .mkdn, .md
  24
+  * Textile: .textile
  25
+  * HTML: .html
  26
+
  27
+Even though page files may be placed in any directory, there is still only a
  28
+single namespace for page names, so all page files should have globally unique
  29
+names regardless of where there are located in the repository.
  30
+
  31
+CSS and JavaScript (.css and .js) files are automatically detected and
  32
+injected into page files that live at the same directory level or lower. This
  33
+allows you to easily apply CSS and JS to specific sets of pages.
  34
+
  35
+
  36
+## WIKI LINKS
  37
+
  38
+Wiki links in Gollum are processed before page content is converted into HTML.
  39
+They take the following form:
  40
+
  41
+    [[Page Name]]
  42
+
  43
+If you'd like the link text to be something other than the page name, you can
  44
+use the advanced form:
  45
+
  46
+    [[Page Name | Alternate Text]]
  47
+
  48
+The above wiki links will create a link to the corresponding page file named
  49
+`page-name.ext` where `ext` may be any of the allowed extension types. The
  50
+conversion is as follows:
  51
+
  52
+  1. Replace any non-alpha characters with a dash
  53
+  2. Lowercase all alpha characters
  54
+
  55
+Here are a few more examples:
  56
+
  57
+    [[Tom "TPW" Preston-Werner]] -> tom--tpw--preston-werner.ext
  58
+    [[Quantum Physics | quantum]] -> quantum-physics.ext
  59
+
  60
+The page file may exist anywhere in the directory structure of the repository.
  61
+Gollum does a breadth first search and uses the first match that it finds.
  62
+
  63
+## STATIC LINKS
  64
+
  65
+To link to static files that are contained in the Gollum repository you should
  66
+use the static link tag. Because this tag produces a URL instead of a full
  67
+link tag, it is contained within single brackets. It uses the `file:`
  68
+identifier to mark the contents as a static file reference. Static links are
  69
+processed before page content is converted into HTML.
  70
+
  71
+You can use either absolute or relative paths to specify the file location.
  72
+Absolute paths (that start with a slash) are bound to the repository root.
  73
+
  74
+    [file:/gollum.pdf]
  75
+    [file:/docs/gollum.pdf]
  76
+
  77
+Relative paths (without a beginning slash) are referenced from the location of
  78
+the page file. For example, if your page file is `documentation.md` and is
  79
+stored in the `docs` directory under the repository root, then the following
  80
+link in `documentation.md` will produce a URL to `/docs/gollum.pdf`:
  81
+
  82
+    [file:gollum.pdf]
  83
+
  84
+In Markdown, a link would take the following form:
  85
+
  86
+    [Gollum Manual]([file:gollum.pdf])
  87
+
  88
+In Textile, it would look like this:
  89
+
  90
+    "Gollum Manual":[file:gollum.pdf]
  91
+
  92
+And in HTML, like so:
  93
+
  94
+    <img src="[file:gollum.pdf]" alt="Gollum Manual" />
  95
+
  96
+
  97
+## ESCAPING WIKI AND STATIC LINKS
  98
+
  99
+If you need the literal text of a wiki or static link to show up in your final
  100
+wiki page, simply preface the link with a single quote (like in LISP):
  101
+
  102
+    '[[Wiki Link]]
  103
+    '[file:foo.jpg]
  104
+
  105
+This is useful for writing about the link syntax in your wiki pages.
  106
+
  107
+
  108
+## SYNTAX HIGHLIGHTING
  109
+
  110
+In Markdown and Textile page files you can get automatic syntax highlighting
  111
+for a wide range of languages (courtesy of Pygments) by using the following
  112
+syntax:
  113
+
  114
+    ```ruby```
  115
+    def foo
  116
+      puts 'bar'
  117
+    end
  118
+    ```
  119
+
  120
+The block must start with three backticks (as the first characters on the
  121
+line). After that comes the name of the language that is contained by the
  122
+block. The language must be one of the `short name` lexer strings supported by
  123
+Pygments. See the [list of lexers](http://pygments.org/docs/lexers/) for valid
  124
+options. Following the language name you may add an additional three backticks
  125
+for aesthetic reasons (but this is not required). The block must end with at
  126
+least three backticks as the first characters on a line. You may add more
  127
+backticks for balance if you like.
  128
+
  129
+
  130
+## API DOCUMENTATION
  131
+
  132
+The Gollum API allows you to retrieve raw or formatted wiki content from a Git
  133
+repository, write new content to the repository, and collect various meta data
  134
+about the wiki as a whole.
  135
+
  136
+Initialize the Gollum::Repo object:
  137
+
  138
+    # Require rubygems if necessary
  139
+    require 'rubygems'
  140
+
  141
+    # Require the Gollum library
  142
+    require 'gollum'
  143
+
  144
+    # Create a new Gollum object by initializing it with the path to the
  145
+    # Git repository.
  146
+    gollum = Gollum.new("my-gollum-repo.git")
  147
+    # => <Gollum::Repo>
  148
+
  149
+Get the latest HTML formatted version of the given canonical page name:
  150
+
  151
+    page = gollum.formatted_page('page-name')
  152
+    # => <Gollum::Page>
  153
+
  154
+    page.data
  155
+    # => "<h1>My wiki page</h1>"
  156
+
  157
+    page.format
  158
+    # => :markdown
  159
+
  160
+    vsn = page.version
  161
+    # => <Gollum::Version>
  162
+
  163
+    vsn.id
  164
+    # => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
  165
+
  166
+Get the latest raw version of the given canonical page name:
  167
+
  168
+    gollum.raw_page('page-name')
  169
+    # => <Gollum::Page>
  170
+
  171
+    page.data
  172
+    # => "# My wiki page"
  173
+
  174
+    page.format
  175
+    # => :markdown
  176
+
  177
+    page.version
  178
+    # => <Gollum::Version>
  179
+
  180
+Get a list of versions for a given canonical page name:
  181
+
  182
+    vsns = gollum.page_versions('page-name')
  183
+    # => [<Gollum::Version, <Gollum::Version, <Gollum::Version>]
  184
+
  185
+    vsns.first.id
  186
+    # => '3ca43e12377ea1e32ea5c9ce5992ec8bf266e3e5'
  187
+
  188
+    vsns.first.date
  189
+    # => Sun Mar 28 19:11:21 -0700 2010
  190
+
  191
+Get a specific version of a given canonical page file:
  192
+
  193
+    gollum.formatted_page('page-name', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
  194
+    gollum.raw_page('page-name', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
  195
+
  196
+Get the latest version of a given static file:
  197
+
  198
+    file = gollum.static_file('asset.js')
  199
+    # => <Gollum::File>
  200
+
  201
+    file.data
  202
+    # => "alert('hello');"
  203
+
  204
+    file.version
  205
+    # => <Gollum::Version>
  206
+
  207
+Get a specific version of a given static file:
  208
+
  209
+    gollum.static_file('asset.js', '5ec521178e0eec4dc39741a8978a2ba6616d0f0a')
  210
+
  211
+Write a new version of a given canonical page file (the file will be created
  212
+if it does not already exist) and commit the change.
  213
+
  214
+    gollum.write_page('page-name', 'My wiki page contents')
  215
+
  216
+Write a new version of a given canonical page file and specify a commit
  217
+message:
  218
+
  219
+    gollum.write_page('page-name', 'My wiki page contents', 'commit message')
  220
+
  221
+To delete a page and commit the change:
  222
+
  223
+    gollum.delete_page('page-name')
  224
+
  225
+Once again, you can optionally specify a commit message:
  226
+
  227
+    gollum.delete_page('page-name', 'commit message')

0 notes on commit c787570

Please sign in to comment.
Something went wrong with that request. Please try again.