A simple, Git-powered wiki with a sweet API and local frontend.
gollum -- A git-based Wiki
See the wiki for extensive documentation, along with screenshots of Gollum's features.
DESCRIPTION
Gollum is a simple wiki system built on top of Git. A Gollum Wiki is simply a git repository of a specific nature:
A Gollum repository's contents are human-editable text or markup files.
Pages may be organized into directories any way you choose.
Other content can also be included, for example images, PDFs and headers/footers for your pages.
Gollum pages:
Gollum strives to be compatible with GitHub and GitLab wikis.
Gollum supports advanced functionality like:
Gollum runs both on Unix-like systems and on Windows.
Gollum runs either using 'normal' Ruby (MRI) or JRuby (Ruby on the Java Virtual Machine). On Windows, Gollum runs only using JRuby (either from source, or prebuilt).
On MRI, Gollum uses the rugged git library, while on JRuby/Java it utilizes the rjgit and JGit libraries. See here for more info.
INSTALLATION As a Ruby Gem
Ruby is best installed either via RVM or a package manager of choice. Then simply:
gem install gollum
Installation examples for individual systems can be seen here.
To run, simply:
gollum /path/to/wiki
where /path/to/wiki
is an initialized Git repository.http://localhost:4567
in your browser.Via Docker
See here for instructions on how to run Gollum via Docker.
As a web application resource (Java)
The latest Release of Gollum will always contain a downloadable gollum.war
file that can be directly executed on any system with a working Java installation:
java -jar gollum.war -S gollum <your-gollum-arguments-here>
Misc
See below for information on running Gollum from source, as a Rack app, and more.
MARKUPS
Gollum allows using different markup languages on different wiki pages. It presently ships with support for the following markups:
You can easily activate support for other markups by installing additional renderers (any that are supported by github-markup):
gem install asciidoctor
gem install creole
gem install wikicloth
gem install org-ruby
perl
command must be available on your command line)
Pod::Simple
from CPAN.docutils
for pythongem install RedCloth
By default, Gollum ships with the kramdown
gem to render Markdown. However, you can use any Markdown renderer supported by github-markup. This includes CommonMark support via the commonmarker
gem. The first installed renderer from the list will be used (e.g., redcarpet
will NOT be used if github/markdown
is installed). Just gem install
the renderer of your choice.
See here for instructions on how to use custom rendering gems and set custom options.
RUNNING FROM SOURCE
git clone https://github.com/gollum/gollum
cd gollum
[sudo] bundle install
bundle exec bin/gollum
http://localhost:4567
in your browser.Rack
Gollum can also be run with any rack-compatible web server. More on that over here.
Rack, with an authentication server
Gollum can also be run alongside a CAS (Central Authentication Service) SSO (single sign-on) server. With a bit of tweaking, this adds basic user-support to Gollum. To see an example and an explanation, navigate over here.
Service
Gollum can also be run as a service. More on that over here.
CONFIGURATION
Gollum comes with the following command line options:
Option Arguments Description
--host [HOST] Specify the hostname or IP address to listen on. Default: '0.0.0.0'.1
--port
[PORT]
Specify the port to bind Gollum with. Default: 4567
.
--config [FILE] Specify path to Gollum's configuration file.
--ref
[REF]
Specify the git branch to serve. Default: master
.
--bare none Tell Gollum that the git repository should be treated as bare.
--adapter
[ADAPTER]
Launch Gollum using a specific git adapter. Default: rugged
.2
--base-path
[PATH]
Specify the leading portion of all Gollum URLs (path info). Setting this to /wiki
will make the wiki accessible under http://localhost:4567/wiki/
. Default: /
.
--page-file-dir [PATH] Specify the subdirectory for all pages. If set, Gollum will only serve pages from this directory and its subdirectories. Default: repository root.
--static, --no-static none Use static assets. Defaults to false in development/test, true in production/staging.
--assets [PATH] Set the path to look for static assets.
--css
none
Tell Gollum to inject custom CSS into each page. Uses custom.css
from wiki root.3
--js
none
Tell Gollum to inject custom JS into each page. Uses custom.js
from wiki root.3
--no-edit none Disable the feature of editing pages.
--local-time none Use the browser's local timezone instead of the server's for displaying dates. Default: false.
--follow-renames, --no-follow-renames none Follow pages across renames in the History view. Default: true.
--allow-uploads
[MODE]
Enable file uploads. If set to dir
, Gollum will store all uploads in the /uploads/
directory in repository root. If set to page
, Gollum will store each upload at the currently edited page.4
--mathjax
none
Enables MathJax (renders mathematical equations). By default, uses the TeX-AMS-MML_HTMLorMML
config with the autoload-all
extension.5
--critic-markup none Enable support for annotations using CriticMarkup.
--irb none Launch Gollum in "console mode", with a predefined API.
--h1-title
none
Tell Gollum to use the first <h1>
as page title.
--no-display-metadata none Do not render metadata tables in pages.
--user-icons
[MODE]
Tell Gollum to use specific user icons for history view. Can be set to gravatar
, identicon
or none
. Default: none
.
--mathjax-config
[FILE]
Specify path to a custom MathJax configuration. If not specified, uses the mathjax.config.js
file from repository root.
--template-dir [PATH] Specify custom mustache template directory. Only overrides templates that exist in this directory.
--template-page none Use _Template in root as a template for new pages. Must be committed.
--emoji
none
Parse and interpret emoji tags (e.g. :heart:
) except when the leading colon is backslashed (e.g. :heart:
).
--default-keybind
none
Set the default keybinding for the editor. Can be set to vim
, or emacs
.
--lenient-tag-lookup none Internal links resolve case-insensitively, will treat spaces as hyphens, and will match the first page found with a certain filename, anywhere in the repository. Provides compatibility with Gollum 4.x.
--help none Display the list of options on the command line.
--version none Display the current version of Gollum.
--versions none Display the current version of Gollum and auxiliary gems.
Notes:
0.0.0.0
IP address allows remote access. Should you wish for Gollum to turn into a personal Wiki, use 127.0.0.1
.--adapter
, you should probably read this first.--css
or --js
is used, respective files must be committed to your git repository or you will get a 302 redirect to the create a page.--allow-uploads
is used.Config file
When --config
option is used, certain inner parts of Gollum can be customized. This is used throughout our wiki for certain user-level alterations, among which customizing supported markups will probably stand out. See here for documentation about settings configurable in config.rb
.
All of the mentioned alterations work both for Gollum's config file (config.rb
) and Rack's config file (config.ru
).
CONTRIBUTING
Please consider helping out! See CONTRIBUTING for information on how to submit issues, and how to start hacking on gollum.
Twice a month we will interview people behind open source businesses. We will talk about how they are building a business on top of open source projects.
We'll never share your email with anyone else.