Please update to gollum 5.1.2 to counter a recent exploit. More info will follow after CVE is assigned.
Gollum version 5.0 is out! See here for a list of changes and new features compared to Gollum version 4.x, and see some Screenshots of Gollum's features.
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:
- May be written in a variety of markups.
- Can be edited with your favourite system editor or IDE (changes will be visible after committing) or with the built-in web interface.
- Can be displayed in all versions, reverted, etc.
- Gollum strives to be compatible with GitHub wikis (see
--lenient-tag-lookup
) - Gollum supports advanced functionality like:
- UML diagrams
- BibTeX and Citation support
- Annotations using CriticMarkup
- Mathematics via MathJax
- Macros
- Redirects
- RSS Feed of latest changes
- ...and more
Gollum runs on Unix-like systems using its adapter for rugged by default. You can also run Gollum on JRuby via its adapter for RJGit. On Windows, Gollum runs only on JRuby.
- Ruby is best installed either via RVM or a package manager of choice.
- Gollum is best installed via RubyGems:
[sudo] gem install gollum
Installation examples for individual systems can be seen here.
To run, simply:
- Run:
gollum /path/to/wiki
. - Open
http://localhost:4567
in your browser.
See below for information on running Gollum from source, as a Rack app, and more.
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):
- AsciiDoc --
[sudo] gem install asciidoctor
- Creole --
[sudo] gem install creole
- MediaWiki --
[sudo] gem install wikicloth
- Org --
[sudo] gem install org-ruby
- Pod -- requires Perl >= 5.10 (the
perl
command must be available on your command line)- Lower versions should install
Pod::Simple
from CPAN.
- Lower versions should install
- ReStructuredText -- requires python >= 2 (the
python2
command must be available on your command line)- Note that Gollum will also need you to install
docutils
for your Python 2.
- Note that Gollum will also need you to install
- Textile --
[sudo] gem 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.
git clone https://github.com/gollum/gollum
cd gollum
[sudo] bundle install
bundle exec bin/gollum
- Open
http://localhost:4567
in your browser.
Gollum can also be ran with any rack-compatible web server. More on that over here.
Gollum can also be ran 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.
This repo already has the Dockerfile and docker-compose.yaml file to allow for immediate deployment to a web server such as AWS Elastic Beanstalk via Docker. If you make specific changes to this repository you want to then deploy it easily,
- Change the docker-compose.yaml file's Image name from
electronaccelerator/gollum
toyour_docker_username/image_name
- use command
$ docker build -t your_docker_username/image_name .
to build the image. Don't forget the period! - then command
$ docker push your_docker_username/image_name
to push the image to your Docker registry Follow the rest of the stenps by Prakhar Srivastav to deploy the application.
Original Information: Gollum can also be ran via Docker. More on that over here.
Gollum can also be ran as a service. More on that over here.
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. |
--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. |
--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: ). |
--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:
- The
0.0.0.0
IP address allows remote access. Should you wish for Gollum to turn into a personal Wiki, use127.0.0.1
. - Before using
--adapter
, you should probably read this first. - When
--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. - Files can be uploaded simply by dragging and dropping them onto the editor's text area when
--allow-uploads
is used.
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.
All of the mentioned alterations work both for Gollum's config file (config.rb
) and Rack's config file (config.ru
).
Please consider helping out! See CONTRIBUTING for information on how to submit issues, and how to start hacking on gollum.