New: Gollum is now compatible with JRuby. Just run gem install gollum
to install.
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.
- Python 2.5+ (2.7.3 recommended)
- Ruby 1.9.3+ (1.9.3 recommended) (JRuby compatible!)
- Unix like operating system (OS X, Ubuntu, Debian, and more)
- Will not work on Windows with the default grit adapter, but might work via JRuby (please let us know!)
Don't enable --custom-css
, --custom-js
or --mathjax-config
unless you trust every user who has the ability to edit the wiki.
A better solution with more security is being tracked in #665.
The best way to install Gollum is with RubyGems:
$ [sudo] gem install gollum
You may first need to install some additional development packages for your OS.
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 --
gem install asciidoctor
- 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
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.
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.
--adapter [ADAPTER] Git adapter to use in the backend. Defaults to grit.
--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 for the served pages (default: /) Example: --base-path wiki yields the home page accessible at http://localhost:4567/wiki/.
--gollum-path [PATH] Specify the path to the git repository to be served.
--ref [REF] Specify the repository ref to use (default: master).
--bare Specify that the repository is bare (only necessary when using the grit adapter).
--no-edit Restricts editing capability through frontend.
--no-live-preview Disables livepreview.
--live-preview Enables livepreview.
--allow-uploads [MODE] Allows file uploads. Modes: dir (default, store all uploads in the same directory), page (store each upload at the same location as the page).
--mathjax Enables mathjax for rendering mathematical equations. Uses the TeX-AMS-MML_HTMLorMML config with the autoload-all extension by default.
--mathjax-config [SOURCE] Inject custom mathjax config file. Uses mathjax.config.js from root repository by default.
--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).
You can also run gollum with any rack-compatible server by placing configuring a config.ru
file. This allows you to utilize any Rack middleware like Rack::Auth, OmniAuth, etc. See below for an example of a config.ru
. You can define all the options available on the command line by configuring the app's :wiki_options
hash. See here for the names of the options corresponding to the command line switches.
#!/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.
Gollum optionally takes a --config file
. See config.rb for an example.
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.
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.
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:
- Clone down your fork
- Create a thoughtfully named topic branch to contain your change
- Hack away
- Add tests and make sure everything still passes by running
rake
- If you are adding new functionality, document it in the README
- Do not change the version number, I will do that on my end
- If necessary, rebase your commits into logical chunks, without errors
- Push the branch up to GitHub
- Send a pull request to the gollum/gollum project.
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
$ 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
$ bundle install
$ bundle exec rake test
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