Jekyll Plugin als Ruby Gem vorbereiten und veröffentlichen

10 August 2013

Die hier beschriebenen Abläufe gelten großteils auch für Gems ohne Bezug zu Jekyll.

Korrekten Aufbau des Quellcodes vorbereiten

Vorab muss sichergestellt werden, dass die Dateistruktur der Quelldateien korrekt ist.

  • Der Name des Hauptskripts stellt sich aus dem späteren Gem-Namen mit der Dateiendung .rb zusammen und ist im Unterverzeichnis lib abgelegt.
  • Die Gem-Spezifikation liegt im Hauptverzeichnis und trägt den Gem-Namen mit der Dateiendung .gemspec. Sie wird am Einfachsten aus einer Vorlage erstellt.

Beispielstruktur

.
├── jekyll_image_encode.gemspec
├── lib
│   └── jekyll_image_encode.rb
└── README.textile

Das Anbieten der optionalen README-Datei wird dringend empfohlen.

Ruby Gem bauen und testen

# Diese Konstanten müssen den eigenen Gegebenheiten
# entsprechend initialisiert werden
GEM_NAME=jekyll_image_encode
GEM_VERSION=0.0.1
PATH_TO_JEKYLL_SITE=$HOME/jekyll/

# Gem bauen und lokal installieren
cd ${PATH_TO_JEKYLL_SITE}
gem build ${GEM_NAME}.gemspec
gem install ./${GEM_NAME}-${GEM_VERSION}.gem

# Gem in Jekyll Seite laden
echo "require 'jekyll_image_encode'" >> _plugins/ext.rb
jekyll serve

Nun kann man die Funktionalität des neuen Gem im Browser überprüfen.
Danach kann man den Gem mittels gem uninstall ${GEM_NAME} wieder entfernen.

Quellcode in GitHub veröffentlichen

Wichtig: Es wird davon ausgegangen, dass der Gem lokal bereits in ein Git Repository eingepflegt ist.

Zuerst wird ein neues Repository auf GitHub erstellt.
Danach wird das lokale Repository in das soeben auf GitHub erstellte hochladen:

# Diese Konstanten müssen den eigenen Gegebenheiten
# entsprechend initialisiert werden
GITHUB_USER=GSI
GEM_NAME=jekyll_image_encode
 
git remote add origin git@github.com:${GITHUB_USER}/${GEM_NAME}.git
git push -u origin master

Jekyll Gem auf RubyGems.org veröffentlichen

# Diese Konstanten müssen den eigenen Gegebenheiten
# entsprechend initialisiert werden
RUBYGEMS_USER=GSI
curl -u ${RUBYGEMS_USER} https://rubygems.org/api/v1/api_key.yaml > $HOME/.gem/credentials

gem push ${GEM_NAME}-${GEM_VERSION}.gem
gem list -r ${GEM_NAME}

Jeyll Gem in offizielle Jekyll-Dokumentation eintragen

Zum Zeitpunkt des Verfassens dieses Artikels unterhält das Jekyll Projekt eine Liste der verfügbaren Plugins, welche der Datei site/docs/plugins.md des auf GitHub veröffentlichten Quellcodes entspricht.

Mit Hilfe des üblichen GitHub Workflows, kann man die Listung des eigenen Jekyll Plugins beantragen:

  1. Fork des jekyll Projekts erstellen
  2. Datei site/docs/plugins.md entsprechend anpassen
  3. Änderungen per Pull Request senden