Skip to content

Latest commit

 

History

History
230 lines (166 loc) · 8.21 KB

README.md

File metadata and controls

230 lines (166 loc) · 8.21 KB
Raw

gollum -- A wiki built on top of Git

Gem Version Build Status Dependency Status

DESCRIPTION

Gollum is a simple wiki system built on top of Git.

Gollum wikis are simply Git repositories that adhere to a specific format. Gollum pages may be written in a variety of formats and can be edited in a number of ways depending on your needs. You can edit your wiki locally:

  • With your favorite text editor or IDE (changes will be visible after committing).
  • With the built-in web interface.
  • With the Gollum Ruby API.

Gollum follows the rules of Semantic Versioning and uses TomDoc for inline documentation.

SYSTEM REQUIREMENTS

  • Python 2.5+ (2.7.3 recommended)
  • Ruby 1.9.3+ (1.9.3 recommended)
  • Unix like operating system (OS X, Ubuntu, Debian, and more)
  • Will not work on Windows (because of grit)

SECURITY

Don't enable --custom-css or --custom-js unless you trust every user who has the ability to edit the wiki. A better solution with more security is being tracked in #665.

INSTALLATION

The best way to install Gollum is with RubyGems:

$ [sudo] gem install gollum

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

$ 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 -- brew install asciidoc on mac or apt-get install -y asciidoc on Ubuntu
  • Creole -- gem install creole
  • Markdown -- gem install redcarpet
  • GitHub Flavored Markdown -- gem install github-markdown
  • Org -- gem install org-ruby
  • Pod -- Pod::Simple::HTML comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
  • RDoc
  • ReStructuredText -- easy_install docutils
  • Textile -- gem install RedCloth
  • MediaWiki -- gem install wikicloth

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 for all of Gollum's formats and syntactic options.

RUNNING

To view and edit your Gollum repository locally via the built in web interface, simply install the Gollum gem, navigate to your repository via the command line, and run the executable:

$ gollum

This will start up a web server running the Gollum frontend and you can view and edit your wiki at http://localhost:4567. To get help on the command line utility, you can run it like so:

$ gollum --help

This will show you the options you can pass as arguments to the gollum command:

Options:
        --port [PORT]                Bind port (default 4567).
        --host [HOST]                Hostname or IP address to listen on (default 0.0.0.0).
        --version                    Display current version.
        --config [CONFIG]            Path to additional configuration file
        --irb                        Start an irb process with gollum loaded for the current wiki.
        --css                        Inject custom css. Uses custom.css from root repository
        --js                         Inject custom js. Uses custom.js from root repository
        --template-dir [PATH]        Specify custom template directory
        --page-file-dir [PATH]       Specify the sub directory for all page files (default: repository root).
        --base-path [PATH]           Specify the base path.
        --gollum-path [PATH]         Specify the gollum path.
        --ref [REF]                  Specify the repository ref to use (default: master).
        --no-live-preview            Disables livepreview.
        --live-preview               Enables livepreview.
        --allow-uploads              Allows file uploads.
        --mathjax                    Enables mathjax.
        --user-icons [SOURCE]        Set the history user icons. Valid values: gravatar, identicon, none. Default: none.
        --show-all                   Shows all files in file view. By default only valid pages are shown.
        --collapse-tree              Collapse file view tree. By default, expanded tree is shown.
        --h1-title                   Sets page title to value of first h1

Note that the gollum server will not run on Windows because of an issue with posix-spawn (which is used by Grit).

RACK

You can also run gollum with any rack-compatible server by placing this config.ru file inside your wiki repository. This allows you to utilize any Rack middleware like Rack::Auth, OmniAuth, etc.

#!/usr/bin/env ruby
require 'rubygems'
require 'gollum/app'

gollum_path = File.expand_path(File.dirname(__FILE__)) # CHANGE THIS TO POINT TO YOUR OWN WIKI REPO
Precious::App.set(:gollum_path, gollum_path)
Precious::App.set(:default_markup, :markdown) # set your favorite markup language
Precious::App.set(:wiki_options, {:universal_toc => false})
run Precious::App

Your Rack middleware can pass author details to Gollum in a Hash in the session under the 'gollum.author' key.

CONFIG FILE

Gollum optionally takes a --config file. See config.rb for an example.

CUSTOM CSS/JS

The --css flag will inject custom.css from the root of your git repository into each page. custom.css must be commited to git or you will get a 302 redirect to the create page.

The --js flag will inject custom.js from the root of your git repository into each page. custom.js must be commited to git or you will get a 302 redirect to the create page.

API DOCUMENTATION

The Gollum API 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.

CONTRIBUTE

If you'd like to hack on Gollum, start by forking the repo on GitHub:

http://github.com/gollum/gollum

To get all of the dependencies, install the gem first. The best way to get your changes merged back into core is as follows:

  1. Clone down your fork
  2. Create a thoughtfully named topic branch to contain your change
  3. Hack away
  4. Add tests and make sure everything still passes by running rake
  5. If you are adding new functionality, document it in the README
  6. Do not change the version number, I will do that on my end
  7. If necessary, rebase your commits into logical chunks, without errors
  8. Push the branch up to GitHub
  9. Send a pull request to the gollum/gollum project.

RELEASING

Gollum uses Semantic Versioning.

x.y.z

For z releases:

$ rake bump
$ rake release

For x.y releases:

Update VERSION in lib/gollum.rb
$ rake gemspec
$ rake release

BUILDING THE GEM FROM MASTER

$ gem uninstall -aIx gollum
$ git clone https://github.com/gollum/gollum.git
$ cd gollum
gollum$ rake build
gollum$ gem install --no-ri --no-rdoc pkg/gollum*.gem

RUN THE TESTS

$ 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.

$ 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