Generates a static site from a Gollum Wiki.
The easiest way to install gollum-site is with RubyGems:
$ [sudo] gem install gollum-site
Gollum supports several formats for wiki text. In order to generate the various supported formats certain dependencies must be met:
- ASCIIDoc --
brew install asciidoc
- Creole --
gem install creole
- Markdown --
gem install rdiscount
- 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
Static sites can be generated using the executable provided:
$ gollum-site generate
Once a site has been generated (output to "_site" by default) you can use the gollum-site executable to start a web server for the site:
$ gollum-site serve
The executable provides a few options which are described in the help menu:
$ gollum-site --help
The static site generator uses the
Liquid templating system to render wiki
pages. The generator looks for _Layout.html
files to use as templates. Layouts
affect all pages in their directory and any subdirectories that do not have a
layout file of their own.
A layout is a Liquid template applied to a wiki page during static site generation with the following data made available to it:
wiki.base_path
The base path of the Wiki to which the page belongspage.path
The output path of the pagepage.content
The formatted content of the pagepage.title
The title of the pagepage.format
The format of the page (textile, org, etc.)page.author
The author of the last editpage.date
The date of the last edit
A note about wiki.base_path
tl;dr - Don't use "." or "" as base paths. Use "./" if relative paths are required.
The application of base path differs between Gollum page links and the layout.
Gollum uses File.join
to combine the base path and the page link. The layout simply
renders the base path provided by the user. This can result in differing URLs.
Scenario 1: Don't include a forward slash after wiki.base_path in layouts
base_path | Gollum Link | URL | Layout Link | URL |
---|---|---|---|---|
"." | [[Page]] | "./Page" | "{{ wiki.base_path }}Page" | ".Page" |
"" | [[Page]] | "/Page" | "{{ wiki.base_path }}Page" | "Page" |
Scenario 2: Include a forward slash after wiki.base_path in layouts
base_path | Gollum Link | URL | Layout Link | URL |
---|---|---|---|---|
"/" | [[Page]] | "/Page" | "{{ wiki.base_path }}/Page" | "//Page" |
Considering scenario 2 breaks links when using the default base path it is advised to use scenario 1 and not use "." and "" as base paths. Use "./" if relative paths are required.
The gollum-site executable provides the ability to import the default layout to the current wiki. The import command will copy the required "_Layout.html", css and javascript to the current wiki. These files must be committed to the wiki repository before the 'generate' command will recognize them unless you use the "--working" option.
$ gollum-site import
You can generate a static site from untracked/uncommitted changes by using the "--working" flag.
$ gollum-site generate --working
When running the gollum-site server you can enable directory watching to update the static site when changes are made to any of the wiki or static files. This feature only works with the "serve" command.
$ gollum-site serve --watch
This feature requires the directory_watcher gem.
You can customize sanitization with three options:
-
--allow_elements: custom elements allowed, comma separated
-
--allow_attributes: custom attributes allowed, comma separated
-
--allow_protocols: custom protocols in href allowed, comma separated
$ gollum-site generate --allow_elements embed,object --allow_attributes src --allow_protocols irc
If there is a file named .gollumignore
in the root of the repository, the
exclusions it specifies will be used to suppress gollum-site generation
accordingly. The .gollumignore
file uses .gitignore
semantics.
To see gollum-site in action, let's use it to generate a static site from a Gollum Wiki. For this example I will use the Radiant wiki:
$ git clone git://github.com/radiant/radiant.wiki.git
$ cd radiant.wiki
$ gollum-site generate
$ gollum-site serve
Now you can browse to http://localhost:8000 and view the Radiant wiki as a static site.
If you'd like to see generate the radiant wiki with the Gollum layout:
$ gollum-site import # imports a simple layout
$ gollum-site generate --working # this is SLOW
$ gollum-site serve --watch
Now you can browse to http://localhost:8000 and view the Radiant wiki. Additionally, you can make changes to the wiki files that will automatically update in the static site.