gollum

A simple, Git-powered wiki with a local frontend and support for many kinds of markup and content.

13,807

1,575

13,807

View on GitHub

Top Related Projects

docsify

27,539

🃏 A magical documentation site generator.

mkdocs

19,243

Project documentation with Markdown.

jekyll

48,920

:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby

hugo

75,317

The world’s fastest framework for building websites.

Quick Overview

Gollum is a simple, Git-powered wiki system with a built-in web interface. It allows users to create and edit wiki pages using various markup languages, with all changes automatically tracked and versioned in a Git repository. Gollum is designed to be easily customizable and can be used as a standalone application or integrated into other projects.

Pros

Easy setup and integration with existing Git repositories
Supports multiple markup languages (Markdown, AsciiDoc, Org mode, etc.)
Built-in web interface for viewing and editing pages
Customizable through themes and plugins

Cons

Limited built-in user authentication and access control
May require additional setup for advanced features or integrations
Performance can be affected when dealing with large repositories
Learning curve for users unfamiliar with Git concepts

Getting Started

To get started with Gollum, follow these steps:

Install Gollum:

gem install gollum

Create a new Git repository or navigate to an existing one:

mkdir my-wiki
cd my-wiki
git init

Start the Gollum server:

gollum

Open your browser and navigate to http://localhost:4567 to access your wiki.
Create and edit pages using the web interface or by adding files directly to the repository.

Competitor Comparisons

docsify

27,539

🃏 A magical documentation site generator.

Pros of Docsify

Lightweight and fast, with no build process required
Easy to customize with plugins and themes
Supports multiple languages and full-text search

Cons of Docsify

Limited built-in features compared to Gollum
Requires JavaScript to render content, which may affect SEO
Less suitable for large-scale documentation projects

Code Comparison

Docsify (index.html):

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'My Docs',
      repo: 'https://github.com/username/repo'
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>

Gollum (config.rb):

Gollum::Hook.register(:post_commit, :example) do |committer, sha1|
  puts "Committed #{sha1}"
end

Gollum::Page.send :include, MyModule

Gollum::Filter.register(:my_filter, MyFilterClass)

Both Docsify and Gollum are documentation tools, but they have different approaches. Docsify focuses on simplicity and client-side rendering, while Gollum offers more robust features and server-side processing. The choice between them depends on project requirements, team preferences, and scalability needs.

mkdocs

19,243

Project documentation with Markdown.

Pros of MkDocs

Simpler setup and configuration with YAML-based mkdocs.yml file
Built-in themes and easy customization options
Supports Python-based extensions for added functionality

Cons of MkDocs

Limited built-in Git integration compared to Gollum
Requires Python knowledge for advanced customization
Less seamless integration with GitHub wikis

Code Comparison

MkDocs configuration example:

site_name: My Docs
nav:
  - Home: index.md
  - About: about.md
theme: readthedocs

Gollum configuration example:

Gollum::Hook.register(:post_commit, :example) do |committer, sha1|
  puts "Committed #{sha1}"
end

Both Gollum and MkDocs are popular wiki and documentation tools, but they cater to different use cases. Gollum is more tightly integrated with Git and GitHub, making it ideal for wiki-style documentation within Git repositories. MkDocs, on the other hand, offers a more structured approach to documentation with its YAML configuration and theme system, making it suitable for larger documentation projects and static site generation.

sphinx

6,483

The Sphinx documentation generator

Pros of Sphinx

More extensive documentation generation capabilities, supporting multiple output formats (HTML, PDF, ePub)
Built-in support for automatic API documentation generation from source code
Larger ecosystem with numerous extensions and themes available

Cons of Sphinx

Steeper learning curve, especially for non-Python users
Requires more configuration and setup compared to Gollum's simplicity
Less seamless integration with Git workflows

Code Comparison

Sphinx configuration (conf.py):

project = 'My Project'
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
html_theme = 'alabaster'

Gollum configuration (.gollum.js):

module.exports = {
  format: 'markdown',
  css: 'custom.css',
  mathjax: true
}

Sphinx focuses on structured documentation with Python-based configuration, while Gollum emphasizes simplicity and Git integration. Sphinx offers more advanced features for large-scale documentation projects, particularly in software development. Gollum provides a straightforward wiki-like experience, making it ideal for quick documentation and collaborative editing. The choice between the two depends on project complexity, team familiarity, and specific documentation needs.

jekyll

48,920

:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby

Pros of Jekyll

Static site generation, resulting in faster load times and improved security
Extensive theme and plugin ecosystem for customization
Seamless integration with GitHub Pages for easy deployment

Cons of Jekyll

Steeper learning curve, especially for non-technical users
Requires local setup and build process before deployment
Limited dynamic content capabilities without additional tools

Code Comparison

Jekyll (config.yml):

title: My Jekyll Site
description: A static site generator
baseurl: ""
url: "https://example.com"
theme: minima

Gollum (config.rb):

Gollum::Hook.register(:post_commit, :example) do |committer, sha1|
  puts "Committed #{sha1}"
end

Jekyll focuses on configuration through YAML files, while Gollum uses Ruby for more dynamic setup. Jekyll's approach is more declarative, whereas Gollum offers more programmatic control over the wiki behavior.

Both projects serve different purposes: Jekyll as a static site generator and Gollum as a wiki engine. Jekyll excels in creating static websites with a clear separation of content and presentation, while Gollum shines in collaborative documentation and wiki-style content management.

hugo

75,317

The world’s fastest framework for building websites.

Pros of Hugo

Faster build times for large sites
More extensive theming and templating capabilities
Built-in support for multiple content types and taxonomies

Cons of Hugo

Steeper learning curve for beginners
Less intuitive for simple wiki-style documentation
Requires rebuilding the entire site for content changes

Code Comparison

Hugo (config.toml):

baseURL = "https://example.org/"
languageCode = "en-us"
title = "My Hugo Site"
theme = "ananke"

Gollum (config.rb):

Gollum::Hook.register(:post_commit, :update_footer) do |committer, sha1|
  pages = committer.wiki.pages
  pages.each do |page|
    page.update_footer
  end
end

Hugo focuses on static site generation with a powerful configuration system, while Gollum is designed for wiki-style content management with Git integration. Hugo's code emphasizes site-wide settings, whereas Gollum's code demonstrates its extensibility through hooks and direct page manipulation.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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:
- May be written in a variety of markups.
- Can be edited with your favourite editor (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 and GitLab wikis.
- Just clone your GitHub/GitLab wiki and view and edit it locally!
Gollum supports advanced functionality like:
- Diagrams using Mermaid or PlantUML
- BibTeX and Citation support
- Annotations using CriticMarkup
- Mathematics via KaTeX or MathJax
- Macros
- Redirects
- RSS Feed of latest changes
- ...and more

SYSTEM REQUIREMENTS

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:

Run: gollum /path/to/wiki where /path/to/wiki is an initialized Git repository.
Open 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:

Markdown (see below for more information on Markdown flavors)
RDoc

You can easily activate support for other markups by installing additional renderers (any that are supported by github-markup):

AsciiDoc -- gem install asciidoctor
Creole -- gem install creole
MediaWiki -- gem install wikicloth
Org -- 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.
ReStructuredText -- requires python >= 3
- Note that Gollum will also need you to install docutils for python
Textile -- gem install RedCloth

Markdown flavors

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

ENVIRONMENT

Gollum uses the environment variable APP_ENV primarily to control how the underlying Sinatra app behaves:

development â reload the app on every request
production â load the app only once

CONFIGURATION

Gollum comes with the command line options listed below. Note that there are some additional 'minor' options to tweak Gollum's behaviour that do not have commandline options, but can be configured in config.rb.

Option	Arguments	Description
--host	[HOST]	Specify the hostname or IP address to listen on. Default: '0.0.0.0'.¹
--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`.²
--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.³
--js	none	Tell Gollum to inject custom JS into each page. Uses `custom.js` from wiki root.³
--no-edit	none	Disable the feature of editing pages.
--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.⁴
--math	[RENDERER]	Enable rendering of mathematical equations. Valid renderers: mathjax, katex. Default: katex. Add custom configuration for the renderer to math.config.js and commit it to the repo.
--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`.
--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:`).
--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, use 127.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.

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 and options 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.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot