Overview

Relevant source files

Purpose and Scope

Gollum-lib is a Ruby library that provides programmatic access to Git-backed wiki content. It enables applications to read, write, and render wiki pages stored in Git repositories with full version control capabilities. The library handles content transformation through a sophisticated filter pipeline, manages transactional writes to Git, and provides platform abstraction for both MRI Ruby (via libgit2/Rugged) and JRuby (via JGit).

This document provides a high-level overview of gollum-lib's architecture, core components, and operational flows. For detailed information on specific subsystems, see:

Installation and platform requirements: Installation and Setup
Reading and rendering pages: Pages and Files, Markup and Rendering
Writing and updating content: Writing and Modifying Content
Extending functionality: Customization and Extension

Sources: README.md1-18 lib/gollum-lib/wiki.rb1-10 lib/gollum-lib/page.rb1-10

Core Architecture

Gollum-lib is organized into five distinct layers that separate concerns and enable platform portability:

Sources: lib/gollum-lib/wiki.rb1-165 lib/gollum-lib/page.rb1-102 lib/gollum-lib/markup.rb1-90 lib/gollum-lib/git_access.rb lib/gollum-lib/committer.rb

Core Components

Gollum::Wiki - Repository Coordinator

The Gollum::Wiki class serves as the primary entry point and facade for all wiki operations. It coordinates access to pages, files, and the underlying Git repository.

Method	Purpose	Returns
`page(path, version=nil)`	Retrieve a wiki page	`Gollum::Page` or `nil`
`file(name, version=nil)`	Retrieve a static file	`Gollum::File` or `nil`
`write_page(path, format, data, commit)`	Create/overwrite a page	Commit SHA or `Gollum::Committer`
`update_page(page, name, format, data, commit)`	Modify existing page	Commit SHA or `Gollum::Committer`
`delete_page(page, commit)`	Remove a page	Commit SHA or `Gollum::Committer`
`preview_page(name, data, format)`	Create in-memory preview	`Gollum::PreviewPage`

Initialization Options:

wiki = Gollum::Wiki.new(path, {
  :base_path => "/wiki",           # URL prefix for links
  :page_file_dir => "docs",        # Restrict pages to subdirectory
  :ref => "main",                  # Git branch/ref to use
  :filter_chain => [:YAML, :Code, :Tags, :Render],  # Content filters
  :universal_toc => false,         # Generate TOC for all pages
  :allow_editing => true           # Enable/disable writes
})

Sources: lib/gollum-lib/wiki.rb91-165 lib/gollum-lib/wiki.rb174-210 lib/gollum-lib/wiki.rb229-271

Gollum::Page and Gollum::File - Content Entities

These classes represent wiki pages and static files respectively, providing access to content, metadata, and version history.

Key Methods:

page.raw_data - Unprocessed file content from Git
page.formatted_data(&block) - Rendered HTML with filters applied
page.metadata - Extracted YAML frontmatter merged with global metadata
page.versions(options) - All Git commits affecting this page

Sources: lib/gollum-lib/file.rb1-98 lib/gollum-lib/page.rb95-102 lib/gollum-lib/page.rb162-203 lib/gollum-lib/page.rb363-387

Gollum::Markup - Rendering Engine

The Gollum::Markup class orchestrates the content transformation pipeline, converting raw markup to safe HTML through a configurable filter chain.

Supported Formats:

The library supports multiple markup formats through GitHub::Markup integration. Each format is registered in Gollum::Markup.formats:

:markdown - Extensions: md, markdown, mdown, mkdn, mkd
:textile - Extension: textile
:rdoc - Extension: rdoc
:org - Extension: org
:creole - Extension: creole
:mediawiki - Extension: mediawiki, wiki
:asciidoc - Extensions: asciidoc, adoc
:pod - Extension: pod
:rst - Extension: rst

Sources: lib/gollum-lib/markup.rb17-69 lib/gollum-lib/markup.rb84-120 lib/gollum-lib/markup.rb122-145 lib/gollum-lib/markups.rb

Filter System - Two-Phase Pipeline

The filter chain processes content in two phases to prevent filter interference and ensure security:

Extract Phase (Forward): Filters scan content and replace special patterns with SHA-based placeholders Process Phase (Reverse): Filters replace placeholders with final rendered content

Filter Chain Configuration:

Default chain: [:YAML, :BibTeX, :PlainText, :CriticMarkup, :TOC, :Sanitize, :RemoteCode, :Code, :Macro, :Emoji, :PlantUML, :Tags, :PandocBib, :Render]

Each filter implements two methods:

extract(data) - Replace special content with placeholders
process(data) - Replace placeholders with final rendered content

Sources: lib/gollum-lib/wiki.rb158-162 lib/gollum-lib/markup.rb122-145 lib/gollum-lib/filter.rb lib/gollum-lib/filter/tags.rb1-52 lib/gollum-lib/filter/code.rb

Gollum::GitAccess - Cached Git Operations

GitAccess provides an optimized abstraction over Git repository reads with in-memory caching to improve performance for large wikis.

Key Responsibilities:

Maintain cached tree maps for fast page lookups
Defer blob loading until content is actually accessed
Abstract over platform-specific Git adapters
Handle ref resolution (branches, tags, SHAs)

Sources: lib/gollum-lib/git_access.rb lib/gollum-lib/wiki.rb136-139

Gollum::Committer - Write Transactions

The Committer class manages transactional writes to the Git repository, enabling atomic batch operations and automatic working directory synchronization.

Transaction Lifecycle:

Batch Operations:

# Single operation (auto-commits)
wiki.write_page("Page1", :markdown, "Content", commit_details)

# Batch operations (manual commit)
committer = Gollum::Committer.new(wiki, commit_details)
wiki.write_page("Page1", :markdown, "Content 1", :committer => committer)
wiki.write_page("Page2", :markdown, "Content 2", :committer => committer)
committer.commit  # Atomic commit of both pages

Sources: lib/gollum-lib/committer.rb lib/gollum-lib/wiki.rb229-270 lib/gollum-lib/wiki.rb309-322

Content Read Flow

The following diagram shows how content flows from Git storage through rendering to final HTML output:

Sources: lib/gollum-lib/wiki.rb174-183 lib/gollum-lib/page.rb24-42 lib/gollum-lib/page.rb179-192 lib/gollum-lib/markup.rb156-169

Content Write Flow

Write operations follow a transactional pattern with automatic duplicate detection and working directory synchronization:

Sources: lib/gollum-lib/wiki.rb229-231 lib/gollum-lib/committer.rb lib/gollum-lib/wiki.rb315-322

Platform Abstraction

Gollum-lib supports both MRI Ruby and JRuby through a platform-specific adapter layer that abstracts Git operations:

Platform	Adapter Gem	Git Implementation	Native Library
MRI Ruby (CRuby)	`gollum-rugged_adapter`	Rugged	libgit2 (C)
JRuby	`gollum-rjgit_adapter`	RJGit	JGit (Java)

Adapter Selection:

Unified Git API:

Both adapters implement the same interface:

Gollum::Git::Repo - Repository operations
Gollum::Git::Commit - Commit access
Gollum::Git::Blob - File content
Gollum::Git::Tree - Directory trees
Gollum::Git::Index - Staging area for writes

Sources: gemspec.rb1-25 lib/gollum-lib.rb gollum-lib.gemspec gollum-lib_java.gemspec

Extension Points

Gollum-lib provides several mechanisms for customization:

Extension Type	Base Class/Method	Purpose
Custom Filters	`Gollum::Filter`	Add new content processing steps
Custom Macros	`Gollum::Macro`	Create dynamic content generators
Markup Formats	`Gollum::Markup.register()`	Add support for new markup languages
Language Handlers	`Gollum::Filter::Code.language_handlers`	Custom code block rendering
Hooks	`Gollum::Hook.register()`	Post-commit and post-initialization callbacks

Example Hook Registration:

Gollum::Hook.register(:post_commit, :push_to_remote) do |committer, sha|
  # Push changes to remote repository
  system("git push origin #{committer.wiki.ref}")
end

Gollum::Hook.register(:post_wiki_initialize, :setup_cache) do |wiki|
  # Initialize caching layer
  wiki.instance_variable_set('@cache', Cache.new)
end

Sources: lib/gollum-lib/filter.rb lib/gollum-lib/macro.rb lib/gollum-lib/markup.rb42-69 lib/gollum-lib/hook.rb test/test_wiki.rb5-16 README.md210-233

Configuration and Initialization

The wiki is configured through options passed to Gollum::Wiki.new() or by setting defaults on the class:

# Set defaults for all wiki instances
Gollum::Wiki.default_options = {
  :universal_toc => true,
  :mathjax => false,
  :filter_chain => [:YAML, :Code, :Tags, :Render]
}

Gollum::Wiki.default_committer_name = "Gollum Wiki"
Gollum::Wiki.default_committer_email = "wiki@example.com"

# Create wiki with instance-specific overrides
wiki = Gollum::Wiki.new("/path/to/repo.git", {
  :base_path => "/wiki",
  :page_file_dir => "pages",
  :ref => "main",
  :allow_editing => true
})

Common Options:

:base_path - URL prefix for all wiki links (default: "/")
:page_file_dir - Restrict pages to a subdirectory (default: nil)
:ref - Git ref to use (default: "master" or "main")
:filter_chain - Customize content processing pipeline
:universal_toc - Generate table of contents for all pages
:allow_editing - Enable/disable write operations
:css, :emoji, :mathjax - Enable optional features

Sources: lib/gollum-lib/wiki.rb8-41 lib/gollum-lib/wiki.rb91-165 README.md82-90