GOLLUM: Un wiki basé sur git

Gollum est un wiki construit sur le système de gestion de contrôle de source Git. Un wiki de Gollum est simplement un dépôt git de nature spécifique:

• Le contenu d'un référentiel Gollum est éditable par l'homme. Les pages sont des fichiers texte uniques qui peuvent être organisés dans des répertoires comme bon vous semble, à condition qu'ils aient une extension de fichier reconnue. D'autres contenus peuvent également être inclus, par exemple des images, des PDF et des en-têtes / pieds de page.
• Pages Gollum:
• Peut être écrit dans une variété de [langages de marquage] (# balises).
• Peut être édité avec votre éditeur de système préféré ou IDE ou avec l'interface Web intégrée.
• Peut être affiché dans toutes les versions et peut facilement être restauré.
• Gollum prend en charge des fonctionnalités avancées telles que les diagrammes UML, les macros, les métadonnées et plus.

Gollum est petit et léger, mais parvient à mettre en œuvre tout ce qu'on peut raisonnablement souhaiter d'un wiki: liens entre les pages, formatage de texte de base, création, modification et suppression de page, recherche de texte intégral et un grand nombre d'options de formatage de texte.

Varie selon le système d'exploitation, le gestionnaire de paquets et l'installation de Ruby. En règle générale, il faut d'abord installer Ruby, puis Gollum.

1. Il est préférable d’installer Ruby via [RVM] (https://rvm.io/) ou un gestionnaire de package de choix.
2. Il est préférable d’installer Gollum via RubyGems:

[sudo] gem install gollum

Gollum est actuellement livré avec le support des balises suivantes:

• [Markdown] (http://daringfireball.net/projects/markdown/syntax)
• [RDoc] (http://rdoc.sourceforge.net/)

Étant donné que toutes les balises sont rendues par la gemme [github-markup] (https://github.com/github/markup), on peut facilement ajouter une prise en charge pour d'autres balises par une installation supplémentaire:

• [AsciiDoc] (http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) - [sudo] gem install asciidoctor
• [Creole] (http://www.wikicreole.org/wiki/CheatSheet) - [sudo] gem install creole
• [MediaWiki] (http://www.mediawiki.org/wiki/Help:Formatting) - [sudo] gem install wikicloth
• [Org] (http://orgmode.org/worg/dev/org-syntax.html) - [sudo] gem install org-ruby
• [Pod] (http://perldoc.perl.org/perlpod.html) - requiert Perl> = 5.10 (la commande perl doit être disponible sur votre ligne de commande)
  • Les versions inférieures devraient installer Pod :: Simple depuis CPAN.
• [ReStructuredText] (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html) - requiert python> = 2 (la commande python2 doit être disponible sur votre ligne de commande)
  • Il faut également installer docutils pour Python 2. La procédure d'installation peut varier, encore une fois, selon le système d'exploitation et le gestionnaire de paquets.
• [Textile] (http://redcloth.org/hobix.com/textile/quick.html) - [sudo] gem install RedCloth

Par défaut, Gollum est livré avec le gem kramdown pour rendre Markdown. Cependant, on peut utiliser n'importe quel [Rendu de Markdown pris en charge par github-markup] (https://github.com/github/markup/blob/master/lib/github/markup/markdown.rb). Ce qu'il faut retenir, c'est que le premier moteur de rendu installé dans la liste sera utilisé. Ainsi, par exemple, redcarpet ne sera PAS utilisé si github / markdown est installé.

Simplement:

1. Accéder au référentiel git (wiki) via la ligne de commande.
2. Exécuter: gollum.
3. Ouvrer l'url http://localhost:4567 dans le navigateur.

Cela démarrera un serveur Web (WEBrick) exécutant Gollum avec une interface Web, où on pourra voir et éditer le wiki.

1. git clone https://github.com/gollum/gollum
2. cd gollum
3. [sudo] bundle install (peut ne pas toujours être nécessaire).
4. bundle exec bin/gollum * Comme cela, gollum suppose que le wiki cible (référentiel git) est le référentiel du projet lui-même. Si ce n'est pas le cas, exécuter bundle exec bin/gollum <chemin d'accès au wiki>.
5. Ouvrir http://localhost:4567 dans le navigateur.

On peut également exécuter gollum avec n’importe quel serveur compatible avec rack en plaçant ce fichier config.ru dans le référentiel wiki. Cela permet d'utiliser n'importe quel middleware Rack comme Rack::Auth, OmniAuth, etc.

#! / usr / bin / env ruby
besoin de 'rubygems'
nécessite 'gollum / app'

#!/usr/bin/env ruby
require 'rubygems'
require 'gollum/app'

gollum_path = File.expand_path(File.dirname(__FILE__)) # CHANGE THIS TO POINT TO YOUR OWN WIKI REPO
wiki_options = {:universal_toc => false}
Precious::App.set(:gollum_path, gollum_path)
Precious::App.set(:default_markup, :markdown) # set your favorite markup language
Precious::App.set(:wiki_options, wiki_options)
run Precious::App

Le middleware Rack peut transmettre les détails de l'auteur à Gollum dans un hachage de la session sous la clé gollum.author.

Les options disponibles pour le hachage: wiki_options correspondent généralement aux arguments utilisés lors de l'exécution de gollum à partir de la ligne de commande, à quelques exceptions près. Ci-dessous une liste des clés que vous pouvez utiliser pour définir les options de gollum lors de son exécution en tant qu'application Rack.

wiki_options = {}
wiki_options[:css] = true # Equivalent to --css
wiki_options[:js] = true # Equivalent to --js
wiki_options[:template_dir] = path # Equivalent to --template-dir
wiki_options[:page_file_dir] = path # Equivalent to --page-file-dir
wiki_options[:gollum_path] = path # Equivalent to ARGV
wiki_options[:ref] = ref ## Equivalent to --ref
wiki_options[:repo_is_bare] = true # Equivalent to --bare
wiki_options[:allow_editing] = false # # Equivalent to --no-edit
wiki_options[:live_preview] = true # Equivalent to --live-preview
wiki_options[:allow_uploads] = true # Equivalent to --allow-uploads
wiki_options[:per_page_uploads] = true # When :allow_uploads is set, store uploads under a directory named after the page, as when using --allow-uploads page
wiki_options[:mathjax] = true # Equivalent to --mathjax
wiki_options[:mathjax_config] = source # Equivalent to --mathjax-config
wiki_options[:user_icons] = source # Equivalent to --user-icons
wiki_options[:show_all] = true # Equivalent to --show-all
wiki_options[:collapse_tree] = true # Equivalent to --collapse-tree
wiki_options[:h1_title] = true # Equivalent to --h1-title

require 'rack'

class MapGollum
    def initialize base_path
        @mg = Rack::Builder.new do
            map '/' do
                run Proc.new { [302, { 'Location' => "/#{base_path}" }, []] }
            end
            map "/#{base_path}" do
                run Precious::App
            end
        end
    end

    def call(env)
        @mg.call(env)
    end
end

# Rack::Handler does not work with Ctrl + C. Use Rack::Server instead.
Rack::Server.new(:app => MapGollum.new('wiki'), :Port => options['port'], :Host => options['bind']).start

On peut utiliser Gollum en tant que service système:

• Créer un fichier gollum.service.
• Ajouter une ligne ExecStart=…. Cette ligne spécifie l'emplacement de l'exécutable gollum et des arguments pour l'exécuter. Par exemple: ExecStart=/usr/local/bin/gollum --show-all "/home/someuser/wiki/"
• Démarrer le service: [sudo] systemctl start gollum.service

On peut exécuter Gollum en tant que service système, mais sous un utilisateur particulier (root par défaut):

• Ajouter une ligne user=%i au fichier gollum.service et renommer le fichier en gollum@.service.
• Modifier la ligne ExecStart=/usr/local/bin/gollum --show-all "/home/someuser/wiki/" to ExecStart=/usr/local/bin/gollum --show-all "/home/%i/wiki/".
• Démarrer le service: [sudo]systemctl start gollum@<utilisateur-cible>.service, où <utilisateur-cible> est l'utilisateur sous lequel exécuter Gollum.

Il existe une alternative à la configuration précédente: exécuter le service dans une session utilisateur. Pour y parvenir:

• Effectuer les deux premières étapes de la création d’un service système (voir ci-dessus).
• Créer le dossier mkdir -p ~/.config/systemd/user/ et déplacer le fichier gollum.service à cet emplacement. Modifier gollum.service si nécessaire.
• Démarrer le service utilisateur via [sudo] systemctl --user start gollum.

Gollum est livré avec les options de ligne de commande suivantes:

Lorsque l'option –config est utilisée, certaines parties internes de Gollum peuvent être personnalisées.

Toutes les modifications onctionnent à la fois pour le fichier de configuration de Gollum (config.rb) et le fichier de configuration de Rack (config.ru).