Netz - Rettung - Recht (Artikel mit Tag nanoc)

FLOSS'n'net - Aktivitäten im 4. Quartal 2018

nospam@example.com (Thomas Hochstein) — Sun, 30 Dec 2018 16:35:00 +0000

In den letzten drei Monaten des Jahres 2018 habe ich wieder ein wenig - sehr wenig! - Zeit gefunden, mich mit dem einen oder anderen Projekt rund um freie Software (FLOSS) oder das Netz zu beschäftigen. Dabei habe ich folgendes beigetragen:

Serendipity (s9y)

Das Blogsystem Serendipity werkelt auch hinter diesem Blog.

Bei dem s9y-Plugin serendipity_event_markdown habe ich die damit ausgelieferten Bibliotheken Markdown und SmartyPants aktualisiert.
Upgrade Markdown Lib and SmartyPants Lib.

Nanoc

U.a. meine Webseiten generiere ich mit Nanoc, einem Generator für statische Seiten.

Die im blogging helper enthaltene Funktion atom_feed() zur Generierung, nun ja, eines Atom-Feeds habe ich um die Möglichkeit ergänzt, die Titel der automatisch erzeugten Einträge anzupassen, wie dies auch schon für den Inhalt bzw. das Exzerpt der einzelnen Einträge möglich war.
Add title_proc parameter to blogging helper.

Zwei Beiträge in drei Monaten ist … nicht viel. Vielleicht finde ich 2019 wieder mehr Zeit.

Vorherige Aktivitäten-Übersicht: 09/2018

Zeitstempel von Dateien unter Versionsverwaltung

nospam@example.com (Thomas Hochstein) — Mon, 15 Jan 2018 06:15:00 +0000

Die Verwaltung von Dateien in einem Versionskontrollsystem (VCS) wie git hat einen Nachteil: der Zeitstempel im Dateisystem gibt nicht mehr den Zeitpunkt der letzten Änderung an dieser Datei wieder, sondern den Zeitpunkt, zu dem sie zuletzt (ggf. mit vielen anderen Dateien) ausgecheckt wurde.

Für Webseiten bedeutet das, dass man für die Ausgabe des Datums der letzten Änderung nicht mehr auf den Zeitstempel der entsprechenden Datei zurückgreifen kann. Das macht mir nichts aus, denn zum einen verwende ich mittlerweile weitgehend statische Webseiten, bei denen das ohnehin nicht ohne weiteres möglich wäre, und zum anderen bringt dieser Ansatz zwar den Vorteil der Automatisierung mit sich, aber zugleich den - aus meiner Sicht überwiegenden - Nachteil, dass jeder verbesserte Tippfehler, jede unsichtbare Änderung am Seitengerüst als “Update” vermerkt wird, obwohl der Inhalt möglicherweise weiterhin völlig veraltet ist. Ich ziehe es daher vor, selbst zu entscheiden, was als “Änderung” gilt, und dann das Datum der letzten Änderung selbst zu setzen.

So weit, so gut - aber wie sieht das mit Downloaddateien aus?

Zeitstempel von Downloadangeboten passend setzen

Jedenfalls dann, wenn man Downloadangebote nicht nur verlinkt, sondern den Downloadbereich auch als Dateiübersicht zugänglich macht - wie ich es auf meinen Webseiten tue -, ist es für den Nutzer gelinde gesagt verwirrend, wenn der angezeigte Zeitstempel der Dateien nichts mit der letzten Änderung derselben zu tun hat.

Dafür gibt es natürlich verschiedene einfache Lösungen: Zum einen könnte ich darauf verzichten, einen Downloadbereich in diesem Sinne anzuzeigen, und die Dateien einfach nur verlinken. Tatsächlich sind die meisten Downloadangebote irgendwo auf meinen Seiten verlinkt, und ich speichere für sie auch Metadaten wie bspw. das Datum der letzten Änderung, das bei dem Link angezeigt wird, wie bspw. bei meinen Downloads aus dem Bereich des Rettungswesens. Ich schätze es aber gerade, dass man in den Downloadangeboten auch “einfach so” stöbern kann. - Zum anderen könnte ich darauf verzichten, Downloads unter Versionskontrolle zu stellen, und sie in einem gesonderten Archiv speichern. Gerade für Software-Releases - und auch meine FAQs - wäre das vernünftig; beide werden ohnehin in gesonderten git-Repositories versioniert, so dass es nicht erforderlich ist, einzelne Releases nochmal im Repository meiner Webseiten zu speichern. Andererseits gibt es aber Downloads, die nicht selbst unter Versionskontrolle stehen, und - mir viel wichtiger - eine getrennte Speicherung der Downloadangebote würde bedeuten, dass ich meine Webseiten nicht “aus einem Guss” aus dem git-Repository erzeugen bzw. wiederherstellen kann; ich müsste dann den Downloadbereich getrennt sichern und einspielen.

Trotz allem denke ich regelmäßig darüber nach, die Downloadangebote aus der Versionskontrolle herauszunehmen (das ist ja ein wenig auch eine Frage der Größe des Repositories). Bis dahin wollte ich aber eine andere Lösung für das Problem der “falschen” Zeitstempel im Directory-Listing - und eigentlich kann das so schwierig ja nicht sein: immerhin habe ich Metadaten, aus denen sich für jede einzelne Datei im Downloadbereich das Datum der letzten (inhaltlichen) Änderung ergibt. Wie schwer kann es sein, den Zeitstempel - also das Datum der letzten Änderung der Datei im Dateisystem, die sog. modification time oder kurz mtime - passend zu setzen?

Wie sich herausstellt: nicht sehr schwer. Es genügt, ein paar Zeilen als postprocess-Block in der Nanoc-Konfiguration hinzuzufügen:

postprocess do
# iterate over all items starting with /archives/ or /net/usenet/faqs/ with kind “file” or “faq” that have “updated_at” set
items.select { |item| %r<^/(archives|net/usenet/faqs)/> =~ item.identifier && [ ‘file’, ‘faq’ ].include?(item[:kind]) && !item[:updated_at].nil? }.each do |item|
# prefer the “text” representation, if available (for FAQs)
unless item.reps[:text].nil?
path = item.path(rep: :text)
else
path = item.path
end
# use the output files, not the source
path = @config[:output_dir] + path
# change the mtime to “updated_at”
# “updated_at” is part Date (when set to 2017-10-01), part String (when set to ‘2017-10-01’),
# so it has to be converted to strings and parsed (instead of using .to_time)
FileUtils.touch path, :mtime => Time.parse(item[:updated_at].to_s)
end
end

Gut, die Zeitstempel sind jetzt immer noch auffällig, weil ich natürlich nur das Datum der letzten Änderung mitführe, nicht die Uhrzeit, und die Dateien daher scheinbar alle um Mitternacht erzeugt werden, aber damit lässt sich leben. Einziger Nachteil: Die unerwartet “alten” Dateien im Downloadbereich bringen das Dependency-Tracking von Nanoc durcheinander und werden daher bei jedem Durchlauf neu erzeugt, weil die Ausgabedateien (mit einem Zeitstempel von vor einigen Monaten oder Jahren) scheinbar älter sind als die Quelldateien (die frisch aus der Versionskontrolle ausgecheckt wurden und daher einen aktuellen Zeitstempel haben), aber damit lässt sich leben.

Symlinks erzeugen

Außerdem konnte ich so ein weiteres Problem lösen:

Die Downloads meiner Scripts (und anderer Software) tragen die Versionsnummer im Dateinamen, bspw. checkmail-0-6-1.tar.gz für die Version 0.6.1 von checkmail. Ich möchte aber zugleich immer die aktuellste Version unter dem generischen Namen checkmail.tar.gz anbieten. Nichts einfacher als das: checkmail.tar.gz muss ein Symlink auf den jeweils neuesten “versionierten” Dateinamen sein. Das lässt sich so auch in das gir-Repository einchecken … nur bearbeite ich meine Webseiten unter Windows - und da ist das Konzept von symbolic links eher nicht so bekannt. Dieses Problem hatte ich vorübergehend “gelöst”, indem ich einfach zwei identische Dateien gespeichert habe - aber das ist natürlich ein nerviger Hack, der doppelt Platz braucht und einfach nicht elegant ist.

Nachdem ich jetzt ohnehin die Dateien im Downloadbereich nach ihrer Generierung nachbehandle, lassen sich dabei auch direkt die Symlinks erzeugen - zwar immer noch aus einer Platzhalterdatei, aber dafür genügt dann eine leere Datei, die nur den passenden Namen trägt. Mein Ansatz dafür ist folgender (eingefügt in den oben bereits gezeigten Block):

postprocess do
[…]
# use the output files, not the source
path = @config[:output_dir] + path
# generate symlinks
if item[:kind] == ‘file’ && item[:current]
# remove placeholder and symlink generic name (‘myprog.tar.gz’)
# to current file (‘myprog-1-2-17.tar.gz’)
FileUtils.rm path
FileUtils.ln_s item[:current], path
# mtime shall be changed for the current file
path = File.dirname(path) + ‘/’ + item[:current]
end
# change the mtime to “updated_at”
[…]
end

Insgesamt fühlt sich das immer noch wie ein Hack an, aber immerhin nicht mehr ganz so krude.

Nanoc: Upgrade von 3.x auf 4.x

nospam@example.com (Thomas Hochstein) — Fri, 01 Sep 2017 06:55:00 +0000

Nanoc nutze ich schon mehr als drei Jahre zur Erzeugung verschiedener Websites; aber wie das so ist bei verschiedenen und zudem historisch gewachsenen Installationen, je mehr und je komplexer man ein Werkzeug einsetzt, desto größer ist der Angang bei notwendigen Änderungen. Und so habe ich das Upgrade auf Nanoc 4 - über dessen Beta ich damals bereits berichtete - dann auch gut zwei Jahre vor mir hergeschoben.

Nunmehr werden aber endlich alle meine Präsenzen mit Nanoc 4 erzeugt.

Es empfiehlt sich, den Umstieg anhand des Upgrade-Guides vorzunehmen. Ich habe mich entschlossen, das Pattern-Matching auf glob patterns umzustellen, aber bei legacy identifiers zu bleiben, um den Umstellungsaufwand überschaubar zu halten. Außerdem verwende ich häufig Eltern-Kind-Relationen zwischen verschiedenen Items (Seiten), die aber mit den full identifiers (“identifiers with extensions”) nicht mehr unzweideutig bestehen (und, um überhaupt zu funktionieren, einen Rückgriff auf einen Helper benötigen).

An folgenden Stellen der Konfiguration ist daher Hand anzulegen (oder war bei mir Hand anzulegen):

Datenquellen

In der nanoc.yaml muss bei den data_sources (meistens wohl filesystem) ein identifier_type: legacy eingefügt werden (Punkt 3 im “quick upgrade guide”).

Was dort nicht steht: Die Datenquelle muss diese Konfiguration selbst umsetzen. Insbesondere für eigene Datenquellen genügt es also nicht, dort einfach identifier_type: legacy einzufügen. Das festzustellen hat mich einige Zeit gekostet.

Anzusetzten ist daher bei der Erzeugung von Items in der Datenquelle. Dort ist ohnehin der Aufruf Nanoc::Item.new durch new_item zu ersetzen (Punkt 7 im “quick guide”). Das genügt aber nicht; der dritte Parameter dieses Funktionsaufrufs erwartet nämlich entweder einen String (der zu einem Identifier konvertiert wird) oder eine Instanz des Objekts Nanoc::Identifier. Was ich nun in der Dokumentation nicht gefunden habe, ist folgendes: ein String wird immer zu einem full identifier konvertiert! Will man Items mit legacy identifier erzeugen, muss man zwingend Nanoc::Identifier instanziieren. Aus "/user/#{user[:id]}/" wird also bspw. Nanoc::Identifier.new("/user/#{user[:id]}/", type: :legacy).

(Auf meinen Hinweis hin ist das nun der neue Punkt 8 im “quick guide”.)

Rules

Hat man - wie ich - auf glob patterns gesetzt (sonst genügt ein string_pattern_type: legacy in der nanoc.yaml), müssen die Rules angepasst werden. Ich verweise insoweit auf den Abschnitt Enabling glob patterns im Extended upgrade guide und die Dokumentation zu Identifiers and patterns, die man ohnehin einmal studieren sollte.

Wichtig - und im Upgrade-Guide dann doch eher versteckt am Ende dargestellt - ist zudem, dass Identifier keine Strings mehr sind, so dass String-Funktionen auf item.identifier nicht mehr ohne weiteres angewandt werden können (bspw. item.identifier.split). Bei jedem dieser Aufrufe muss daher zuvor eine Konvertierung in einen String erfolgen, alos .to_s eingefügt werden: item.identifier.to_s.split geht. Das gilt auch für Helper-Funktionen u.ä., wo sich solche Aufrufe finden können. (Das hat in meinem Fall am meisten Zeit gekostet; auf die Lösung kam ich erst nach Lektüre der Beiträge der letzten Jahre in der Nanoc-Mailingliste).

Weitere Änderungen:

In compile-Regeln entfällt bei filter, layout und snapshot ein ggf. vorangestelltes rep. (“quick guide”, Punkt 5).
Falls jemand im preprocess-Block Items erzeugt, sollte er statt Nanoc::Item.new jetzt @items.create verwenden (“quick guide”, Punkt 6).
Überall, wo auf reps[0] zugegriffen wird, muss stattdessen .reps[:default] stehen (“quick guide”, jetzt Punkt 9).
Entsprechend muss .rep_named(:something) durch .reps[:somethink] ersetzt werden (“quick guide”, jetzt Punkt 10).

Zudem muss man nicht mehr zwischen compile- und routing-Regeln differenzieren: die write-Anweisung erlaubt es, in einer compile-Regel direkt auch festzulegen, wo das Item ausgegeben werden soll. Das erscheint mir zwar praktisch, allerdings (ebenso wie die full identifiers) eher etwas für neue Projekte oder eine Komplettüberarbeitung.

Funktionen, Helper und Filter

Generell ist Nanoc3 durch Nanoc zu ersetzen, bspw. bei Einbinden der mitgelieferten Helper: aus include Nanoc3::Helpers::Blogging wird include Nanoc::Helpers::Blogging usw. (“quick guide”, Punkt 1).
Überall, wo auf @site.config zugegriffen wird, gehört jetzt @config hin (“quick guide”, Punkt 2).
Alle Hinweise aus den vorstehenden Abschnitten gelten entsprechend auch für Helper und Filter.
An Filter übergebene Parameter sind jetzt ebenfalls immutable; man kann sie also nicht mehr verändern. Auch die Zuweisung an eine Variable hilft nicht. Man kann aber ggf. den Inhalt in eine Variable kopieren: params_mutable = filterparams.dup.

Fazit

Der Upgrade-Guide ist gut, deckt aber nicht (unmittelbar) alle Fußangeln und Fallen ab; man sollte etwas Zeit für trial and error einkalkulieren, insbesondere für größere, komplexere Projekte.

nanoc-dejure 1.2 released

nospam@example.com (Thomas Hochstein) — Mon, 21 Aug 2017 09:00:00 +0000

Mein Nanoc-Filter für die juristische Vernetzungsfunktion von dejure.org steht nun in der Version 1.2 zur Verfügung und ist damit - endlich - auch mit der aktuellen Nanoc-Version 4.x kompatibel.

Dazu gehören folgende Neuerungen:

Die automatische Verlinkung kann für Überschriften (die HTML-Elemente <h1> bis <hx>) deaktiviert werden¹.
Verlinkungen erfolgen mit HTTPS als Protokoll².
Kompatibilität mit Nanoc 4.

Beides ist implementiert, scheint aber bei Tests noch nicht richtig zu funktionieren. Ich hoffe, dafür noch eine Lösung finden zu können, bin bislang aber ratlos, nachdem im Wesentlichen dieselbe Implementation für das Serendipity-Plugin, das auch hier im Blog läuft, probemlos funktioniert. ↩︎
Siehe Fußnote 1. ↩︎

Externe Datenquellen für nanoc

nospam@example.com (Thomas Hochstein) — Mon, 24 Jul 2017 05:30:00 +0000

Bereits vor gut zwei Jahren hatte ich berichtet, wie man nanoc mit einer (MySQL-)Datenbank als Datenquelle betreiben kann, und auf die entsprechende Dokumentation verwiesen. Schon damals hatte ich angemerkt, dass sich in dem dort gezeigten Weg möglicherweise ein Zwischenschritt einsparen lässt. Dies habe ich dann mittlerweile auch erfolgreich getestet.

Das Beispiel aus der nanoc-Dokumentation

Das in der nanoc-Dokumentation gezeigte Beispiel generiert aus jedem Datensatz in der Datenbank ein Item (also im Prinzip ein Dokument), das keinen Inhalt hat, aber die einzelnen Datenbankfelder als Attribute enthält, und erzeugt diese “leeren” Seiten unter /external/hr/employees/. Das ergibt sich aus dem Zusammenwirken des Prefixes items_root: /external/hr in der nanoc.yaml einerseits und der Funktion zum Erzeugen von Items in der Definition der Datenquelle andererseits:

def items
@db[:employees].map do |employee|
new_item(
”,
employee,
“/employees/#{employee[:id]}”
)
end
end

Für jeden Datensatz wird ein Item /employees/ID/ (also für den Datensatz mit dem Feld id: 1 ein Item /employees/1/) erzeugt, dem der Pfad /external/hr vorangestellt wird (also im Beispiel /external/hr/employees/1/).

Alle diese Seiten dort sind leer, weshalb ihre Erzeugung im Beispiel auch unterdrückt wird. Von ihnen werden nur die Attribute (“Metadaten”) benötigt, um ein Verzeichnis mit allen Mitarbeitern zu erstellen.

Meine Anwendung für d-e-n.net

Diese Lösung hatte ich für die “Schreiberliste von de.etc.notfallrettung” übernommen.

Da ich dort aber nicht nur eine Liste der Nutzer, sondern für jeden auch eine Profilseite benötige, war ich zweischrittig vorgegangen: in einem ersten Schritt wurden - wie im Beispiel - die Daten eingelesen und leere Seiten (unter /_external/db/users/ID) erzeugt und in einem zweiten Schritt aus den Attributen dieser leeren Seiten entsprechende Profilseiten erstellt, indem im preprocess-Block der Rules eine entsprechende Funktion aufgerufen wurde.

Schon damals fand ich das recht ineffizient: einmal “leere” Seiten nur mit Attributen erstellen, deren Ausgabe unterdrücken und dann für jedes dieser “virtuellen” Items noch einmal eine Seite erzeugen, die dann ausgegeben wird? Warum nicht den ersten Schritt entfallen lassen und direkt die Profilseiten erstellen?

Gesagt, (zwei Jahre später) getan: es genügt, new_item() statt des “leeren” Inhalts den passenden Seiteninhalt zu übergeben (und ggf. die notwendigen Zusatzattribute hinzuzufügen):

def items
@db[:employees].map do |employee|
new_item(
“= render ‘profile’”,
{:updated_at => employee[:changedate], :title => employee[:name],
:description => “Profile of #{employee[:name]}”}.merge(employee),
“/employees/#{employee[:id]}”
)
end
end

Dann musste nur noch - neben einigen Anpassungsarbeiten im Code - in der nanoc.yaml entsprechend items_root: auf / gesetzt werden, damit die Daten auch unter /user/ID aufscheinen, und schon war der unnötige Zwischenschritt entfallen.

Der konkrete Code

Die Datenquelle wird dabei bei mir wie folgt in der nanoc.yaml eingebunden:

data_sources:
-
# The type is the identifier of the data source. By default, this will be
# <code>filesystem_unified</code>.
type: filesystem_unified
[…]
-
# Add mysql database (lib/data_sources/user_db)
type: userdb
items_root: /

Definiert wird die Datenquelle dann in lib/data_sources/user_db.rb:

# taken from http://nanoc.ws/docs/guides/using-external-sources/
require ‘sequel’
class UserDataSource < ::Nanoc::DataSource
identifier :userdb
def up
@db = Sequel.mysql2(:host=>’HOSTNAME’, :user=>’USER’, :password=>’PASS’, :database=>’DATABASE’)
end
def items
@db[:users].map do |user|
fullname = [user[:vorname],user[:name]].join ’ ’
# create profile page
Nanoc::Item.new(
“= render ‘profile’”,
{:author => fullname, :created_at => ‘2002-11-14’,
:updated_at => user[:changedate], :title => “Profil von #{fullname}”,
:short => “#{fullname}”, :template => ‘page-container’,
:description => “Profil des Autors #{fullname} in der Newsgroup de.etc.notfallrettung”}.merge(user),
“/user/#{user[:id]}/”
)
end
end
end

Ich arbeite derzeit noch mit dem alten nanoc 3.x, weshalb dort statt new_item() noch Nanoc::Item.new() verwendet wird.

Mit der dargestellten Funktion in der Definition der Datenquelle wird für jeden Datensatz eine Seite (ein Item) erzeugt, die (das) als einzigen Inhalt = render 'profile' enthält. Da in den Rules angegeben ist, dass die Seiten unterhalb von /user/ einen HAML-Filter durchlaufen, wird mithin der Inhalt der Datei profile im Verzeichnis /layouts/ eingefügt - das Template für alle Profilseiten. Mit dem ERB-Filter wäre entsprechend <%= render 'profile' %> einzufügen. Die erzeugte Seite bzw. das erzeugte Item erhält überdies alle Felder aus dem Datensatz als Attribute übergeben, verbunden mit weiteren, zusätzlichen Attributen wie :author oder :title. Am Schluss bekommt die Seite / das Item einen Identifier unter Nutzung des Datensatzfeldes id, für id: 1 also dementsprechend /user/1/.

Fertig!

Release-Prozess für FAQs

nospam@example.com (Thomas Hochstein) — Mon, 29 May 2017 05:30:00 +0000

Die Überschrift klingt etwas bombastischer, als der Inhalt es ist …

Seit etlichen Jahren nutze ich git zur Verwaltung sowohl meiner Software als auch für die von mir betreuten FAQs. Da lag es nahe, auch die Veröffentlichung neuer Fassungen derselben (“Releases”) nach Möglichkeit zu automatisieren. Für Software bedeutet das, die einzelnen Bestandteile in einen Tarball zu packen, vielleicht Readme-Dateien zu erstellen, usw.; für FAQs ist ggf. zur reinen Textfassung eine HTML-Fassung zu erstellen, was sich insbesondere anbietet, wenn die Textfassung bereits aus Markdown besteht.

Für meine alten Webseiten hatte ich einige entsprechende Scripts geschrieben - eine Textdatei (FAQ) aus einem Git-Repository zu holen und daraus ggf. noch eine HTML-Datei zu erstellen ist ja nun kein Hexenwerk. Bisher geschah das einfach “live” auf dem Webserver. Für meine neue Homepage war es mir aber wichtig, die gesamte Webpräsenz jederzeit neu generieren zu können, und das wiederum erforderte, dass sich die “fertige” FAQ (Text und HTML) dann auch im Repository für die Webseiten findet - oder von nanoc aus diesem erzeugt werden kann.

Derzeitiger Stand

Daher gibt es jetzt ein nanoc-Kommando, das diese Aufgaben wahrnimmt:

Optional wird als erstes das Webseiten-Repository frisch ausgescheckt (d.h. dis bisherige Fassung gelöscht und durch eine komplett neue ersetzt).
Dann wird die betreffende FAQ ausgecheckt, entweder als Textdatei gleichen Namens wie das Repository, oder als Textdatei aus meinem Repository für vermischte kleine FAQs. In jedem Fall erhält sie die Endung .md für Markdown.
Die Metadaten für die FAQ - die vor dem ersten Checkout angelegt sein müssen - werden aktualisiert, insbesondere Änderungsdatum und Version, soweit vorhanden.
Danach werden die Änderungen ins Repository committed und können dann entweder nochmals geprüft oder direkt “in einem Rutsch” in das Webseiten-Repository gepushed werden.

nanoc selbst wiederum erzeugt aus jeder FAQ eine Textfassung - so wie sie im Repository liegt - und, wenn dies nicht unterdrückt wird, auch eine HTML-Fassung, die dann in die Navigation eingebunden wird. Dabei werden die “Pseudo-Header” am Anfang einer FAQ (Posting-frequency oder Last-modified) entfernt. Die Veröffentlichung einer HTML-Fassung erfolgt derzeit aber nur, wenn die Textfassung auch wirklich Markdown ist - das gilt bisher noch nicht für alle FAQs.

Die notwendigen Metadaten stecken in einer gleichnamigen .yaml-Datei, die für nanoc Teil der FAQ ist. Ebenso habe ich das im übrigen auch für alle Downloads (PDF-Dateien, Tarballs o.ä.) gelöst: es gibt immer eine gleichnamige Datei mit der Endung .yaml, die Informationen über den Bearbeitungsstand, die Versionsnummer oder (bei Software) auch das Repository und den Bugtracker enthält. Mit diesen Metadaten können dann Download-Links und Infokästen erzeugt werden.

Überlegungen für die Zukunft

Zukünftig würde ich gerne auch HTML-Fassungen der anderen FAQs erzeugen, möglicherweise dann nicht aus einer Textfassung, die aus Markdown besteht, sondern aus einem übergeordneten Format (Asciidoc?), aus dem sich HTML und eine etwas ansehnlichere Textfassung als Markdown mit komplexen Formatierungen erzeugen lassen.

Und der deutlich aufwendigere zweite Teil des “Release-Managements” wird dann die Erzeugung von Software-Releases sein, nach Möglichkeit mit einem generischen Script. Dazu gehört nicht nur das Erzeugen eines Tarballs (ggf. nur mit den Dateien, die auch zum Release gehören), sondern auch das Umkopieren älterer Fassungen und das Aktualisieren der Metadaten. Letzteres wird sich grundsätzlich wie bei FAQs lösen lassen, erfordert aber das Auslesen der Daten, die sich bei einer FAQ in den Pseudo-Headern finden, namentlich der Version und des Release-Datums. In einem weiteren Schritt wäre es dann auch schon, wenn aus README-Dateien automatisch Webseiten als Bestandteil meiner Webpräsenz erzeugt würden. Theoretisch ist das alles denkbar, praktisch werde ich darüber auch tatsächlich noch einige Zeit nachdenken müssen.

Insoweit ist es vielleicht ganz gut, dass ich derzeit gar keine Zeit habe, irgendwelche Programme zu schreiben …

nanoc-dejure 1.0 released

nospam@example.com (Thomas Hochstein) — Fri, 26 May 2017 05:10:00 +0000

Drei Wochen nach der ersten Fassung meines nanoc-Filters für die juristische Vernetzungsfunktion von dejure.org kann ich nun die Version 1.0 präsentieren.

Neben einem Changelog und einer (englischsprachigen) Readme-Datei gibt es folgende Neuerungen:

Das Cache-Verzeichnis wird jetzt auch dann korrekt erzeugt, wenn das übergeordnete tmp-Verzeichnis noch fehlt.
Die Gültigkeitsdauer des Caches beträgt künftig standardmäßig sieben (und nicht nur vier) Tage. Sie ist außerdem konfigurierbar.
Dokumente ohne irgendwelche hinzuzufügenden Links werden platzsparender gecached.
Der Aufruf der API erfolgt nunmehr über HTTPS.
Einzelne Dokumente können durch Hinzufügen des Textes  irgendwo auf der Seite von der Bearbeitung durch den Filter ausgenommen werden.

nanoc commands

nospam@example.com (Thomas Hochstein) — Mon, 22 May 2017 04:05:00 +0000

Vergangene Woche schrieb ich über Aliase für Git - und heute möchte ich etwas ähnliches für nanoc vorstellen.

nanoc ermöglicht es nämlich, eigene Kommandos in Form von Ruby-Scripts zu definieren, die dann in commands/ gespeichert werden und - bspw. als commands/COMMAND.rb - mit nanoc COMMAND ausgeführt werden. Die Dokumentation hat unter der Überschrift “Writing commands” ein Beispiel dazu und verweist ansonsten auf die Dokumentation von Cri, dem dafür verwendeten Framework.

Die Anwendungsmöglichkeiten dafür sind vielfältig:

Der CCCS hat ein Script, mit dem sich aus einem Template Flyer für die Ankündigung von Vorträgen erzeugen lassen.
Teilweise gebe ich RSS-Feeds als Bestandteil meiner Webseiten aus. Diese Feeds müssen natürlich regelmäßig ausgelesen werden, gefolgt von einem Rebuild der Webseite. Das entsprechende, per Cronjob aufgerufene Script hat, als nanoc-Kommando implementiert, den Vorteil, jederzeit auch so aufgerufen werden zu können und im selben Repository zu stecken wie der Rest der Website.
Die meisten meiner Webseiten haben ein Kommando, mit dem sich die Quelldateien komplett durch einen frischen Checkout ersetzen lassen, wenn bspw. einige Dateien gelöscht worden sind (was sonst bei meinem Workflow dazu führt, dass die Dateien weiter vorhanden bleiben). Im Prinzip wird dabei das Quellverzeichnis komplett geleert, dann ein frischer Git-Checkout vorgenommen, nanoc prune entfernt überzählige compilierte Dateien aus dem Ausgabeverzeichnis, und ggf. werden vor dem Compilieren noch RSS-Feeds ausgelesen oder andere notwendige Operationen vorgenommen, damit alle erforderlichen Daten für den Aufbau der Website zur Verfügung stehen.

Andere Beispiele:

Creating screenshots with nanoc command
A create-post command

Verwendet ihr auch nanoc-Kommandos?

Workflow für die Erstellung und Pflege von Webseiten

nospam@example.com (Thomas Hochstein) — Wed, 17 May 2017 05:20:00 +0000

Ich stelle die von mir betriebenen Webseiten, die nicht auf interaktive Funktionen angewiesen sind, Stück für Stück auf statisch generierte Seiten um, zuletzt meine Homepage. Dabei setze ich auf einen Workflow, der nanoc als static site generator und git als Versionsverwaltungssystem umfasst und dafür sorgt, dass Änderungen der Seiten automatisch eingespielt werden.

Entwicklung, Test und Veröffentlichung

Bei Verwendung eines static site generators werden die Webseiten zunächst aus Quelldateien erzeugt und müssen dann veröffentlicht, d.h. in das passende Verzeichnis des Webservers befördert werden, der sie anzeigen soll. Darüber hinaus ist es generell sinnvoll, “Code” im weitesten Sinne - und dazu gehören dann auch HTML- und CSS-Dateien bzw. die Quellen, aus denen diese erzeugt werden - in einem Versionsverwaltungssystem zu speichern, in dem Änderungen nachverfolgbar sind und wo jederzeit auf ältere Versionen zurückgegriffen werden kann. Nimmt man dies zusammen, unterscheiden sich Webseiten damit letztlich kaum mehr von Webapplikationen oder anderer Software: es gibt den Quellcode und das Kompilat (die fertigen Seiten, das ablauffähige Programm), Quellcode muss verwaltet und das Ergebnis getestet und schließlich veröffentlicht (deployed) werden.

Für die drei Schritte - entwickeln, testen, veröffentlichen - werden zumeist mehrere Rechner (Systeme, Umgebungen) benötigt, die unterschiedlichen Zwecken dienen:

Entwicklungsumgebung
Der Rechner, auf dem die Seiten entworfen, bearbeitet und ggf. auch getestet werden.
Git-Server
Git ist zwar ein verteiltes Versionsverwaltungssystem, aber es ist generell sinnvoll, das Repository nicht nur auf dem eigenen Arbeitsrechner vorzuhalten, sondern auch auf (mindestens) einem Server. Das schafft Redundanz und ermöglicht es, auf verschiedenen Rechner zu arbeiten und die Ergebnisse jeweils zu synchronisieren.
Testumgebung
Es ist sinnvoll, ein Testsystem vorzuhalten, dass dem Echtsystem weitgehend entspricht, um testen zu können, ob die Webseiten auch wirklich so aussehen und “funktionieren”, wie man sich das vorstellt.
Echtumgebung
Am Ende des Tages sollen die Webseiten auf einem Rechner im Netz liegen, der sie mithilfe eines Webservers weltweit abrufbar macht.

Grundsätzlich kann man das alles auf ein- und demselben Gerät betreiben: eine im Netz verfügbare Maschine, auf der man sich einloggt und entwickelt, auf der Git verfügbar ist und die zugleich Test- und Echtumgebung darstellt. Meistens wird man aber doch auf dem heimischen Desktoprechner oder dem Laptop arbeiten wollen und einen Webserver (oder auch nur Webspace) irgendwo angemietet haben. Letzteres gilt auch für mich.

Mein Workflow

Ich bearbeite die Quelldateien (den Sourcecode) meiner Webseiten auf meinem Desktoprechner oder dem Laptop unter Windows, zumeist mit Sublime Text, reine Markdown-Dateien manchmal auch mit MarkdownPad.

nanoc unterstützt einen sehr bequemen Testmodus mit eingebautem Webserver: nach dem Compilieren mit nanoc genügt ein nanoc view, um einen Webserver zu starten, der dann unter http://localhost:3000/ die Website zur Ansicht bereitstellt. Leider funktioniert das für mich noch nicht, denn zwar lässt sich nanoc grundsätzlich auch unter Windows installieren und betreiben, aber das für den LESS-Filter erforderliche Ruby-Gem leider nicht - jedenfalls ist mir das nicht gelungen. Daher arbeite ich weiterhin “nach alter Väter Sitte” und lade die geänderten Dateien per SCP bzw. SFTP entweder auf einen lokalen Linux-Server oder direkt auf den externen Webserver hoch bzw. sorge für eine automatische Synchronisierung mit WinSCP. Dort wird dann compiliert und im Browser das Ergebnis angeschaut.

Auch das Veröffentlichen der Seiten unterstützt nanoc mit dem Kommando nanoc deploy, das ein Deployment per git, per rsync oder mittels fog unterstützt. Das ist sicherlich sehr nützlich, wenn man die Webseiten auf dem Entwicklungsrechner testet und dann von dort auf den Webserver überspielt; nachdem nanoc aber auf meinen Windows-Rechnern nicht läuft, gehe ich einen anderen Weg und compiliere direkt auf dem Webserver. Ich lade also den Quellcode hoch, lasse nanoc auf dem Server laufen und das Ergebnis dann unmittelbar in das Webserver-Verzeichnis ausgeben (in der Regel durch ein passend gesetztes output_dir in der nanoc.yaml).

Ich halte regelmäßig neben der aktuellen Fassung meiner Webseiten auch eine Testfassung vor, die ich über eine passwortgeschützte URL aufrufen kann. Das hat den Vorteil, dass ich von überallher testen kann und zudem die Testumgebung und die Echtumgebung identisch sind, weil sie auf demselben Server (in zwei unterschiedlichen virtual hosts) laufen.

Das jeweilige Git-Repository für eine Website hat daher immer mindestens den master- und einen staging-Zweig; im letzteren wird getestet, der erstere enthält die aktuelle Echtversion. Wenn ich einen dieser Zweige per git push auf meinen Git-Server schiebe, wird er automatisch auf den Webserver kopiert (in das Quellverzeichnis für die Echtfassung oder dasjenige für die Testversion der Website), dort compiliert und bereitgestellt. Auch für dieses “Kopieren” oder generell das Aktualisieren einer Website über git gibt es eine Reihe von Möglichkeiten: man kann bspw. einfach das Git-Repository auf dem Webserver auschecken, oder aber man checkt via git archive wirklich nur den Inhalt des Repositorys aus. Ich habe mich für letzteres entschieden; einziger Nachteil ist, das aus dem Repository entfernte Dateien nicht automatisch gelöscht werden, ggf. also “Leichen” verbleiben. Dafür habe ich nicht das komplette Repository mit der ganzen History herumliegen.

Ein Beispiel

In der Praxis sieht das dann ungefähr so aus:

Ich aktualisiere mein lokales Git-Repository auf dem jeweiligen Arbeitsrechner, damit es auf dem aktuellen Stand ist.
Ich verändere oder ergänze meine Webseiten, indem ich die entsprechenden Dateien auf dem Arbeitsrechner bearbeite.
Wenn umfangreichere Tests erforderlich sind, lade ich die geänderten Dateien auf meinen Webserver in das Quellverzeichnis für die Test-Instanz der jeweiligen Website hoch und führe - auf dem Server - nanoc aus, so dass die Testinstanz der jeweiligen Webseiten aktualisiert wird. Im Browser kann ich dann die geänderten Seiten durch Aufruf von http://test.meine-website.example/ ansehen. Alternativ kann ich natürlich auch auf einem anderen Rechner im lokalen Netz testen.
Wenn ich mit dem Ergebnis zufrieden bin, aktualisiere ich den test-Zweig meines lokalen Git-Repositorys und schiebe ihn per git push auf den externen Git-Server.

Dort wird ein post-receive-Hook ausgeführt, der auf dem richtigen Webserver ein PHP-Script mit den passenden Paramtern aufruft. Das Script sorgt dann dafür, dass die Dateien aus dem Git-Repository ausgecheckt werden, und führt danach nanoc aus. Für den test-Zweig des Repositories websites/meine-website auf dem Server git.server.example mit dem Zielverzeichnis /var/www/sources/meine-website/ auf dem Webserver sähe das dann so aus:

$ git archive --format=tar --remote=ssh://git@git.server.example/websites/meine-website test | tar -C /var/www/sources/test.meine-website.example/ -xf -
$ cd /var/www/sources/test.meine-website.example/
$ nanoc

nanoc hat dann als output_dir bspw. /var/www/html/test.meine-website.example/ konfiguriert, was zugleich das DocumentRoot für den virtual host http://test.meine-website.example/ ist.

Will ich später die gesammelten Änderungen aus der Testinstanz auf die Echtinstanz übernehmen, geht das ebenfalls ganz einfach: ich bringe sie in den master-zweig meines Repositorys und veröffentliche diesen: git checkout master; git merge test; git push; git checkout test

Der post-receive-Hook wird das Deployment-Script mit anderen Parametern aufrufen, so dass nicht der test-Zweig, sondern der master-Zweig ausgecheckt und nicht nach /var/www/sources/test.meine-website.example/, sondern nach /var/www/sources/www.meine-website.example/ kopiert wird. Und das ist dementsprechend das DocumentRoot für http://www.meine-website.example/.

Die nanoc-Ausgaben gibt das Deployment-Script aus, so dass der Git-Server sie an den Git-Client übermittelt; sollte nanoc die Compilation also mit einer Fehlermeldung abbrechen, ist das erkennbar und ermöglicht ein manuelles Eingreifen. Ansonsten sind manuelle Eingriffe nur noch erforderlich, wenn eine bereits deployte Datei gelöscht werden muss; es liegt in der Natur der Sache, dass der gewählte Weg über git archive neue und geänderte Dateien (und Verzeichnisse) anlegt, alte Dateien aber nicht löscht.

Conclusio

Viele Wege führen nach Rom; dies ist meiner.

Er lässt sich fraglos vereinfachen; ein Hemmschuh ist insbesondere die Entwicklung unter Windows, die den Workflow erschwert.

Kommentare und Kritik nehme ich gerne entgegen, ebenso wie andere Wege zum selben Ziel.

Vernetzungsfunktion von dejure.org als nanoc-Filter

nospam@example.com (Thomas Hochstein) — Wed, 10 May 2017 05:40:00 +0000

Das - kostenlose - juristische Informationsportal dejure.org bietet nach eigenen Angaben 90% der am häufigsten zitierten deutschen (Bundes-)Gesetze, insgesamt rund 300 an der Zahl, und dazu vor allem eine umfassende Literaturdatenbank mit Urteilen, Anmerkungen und Querverweisen an. Ist ein Gesetz nicht verfügbar, wird der Nutzer auf den entsprechenden Eintrag in der umfassenden Sammlung des deutschen Bundesrechts bei buzer.de - einem weiteren kostenlosen juristischen Informationsdienst - weitergeleitet.

Außerdem stellt dejure.org mit seiner juristischen Vernetzungsfunktion eine Möglichkeit zur “automatischen Verlinkung von Gesetzes- und Rechtsprechungszitaten über eine einfache Schnittstelle” zur Verfügung. Jeder Paragraph eines bei dejure.org (oder buzer.de) erfassten Gesetzes, jede Urteilsfundstelle wird auf Wunsch mit einem passenden Link auf dejure.org hinterlegt. Für eine Vielzahl von Webapplikationen (Blogs, CMS, Foren, Wikis), darunter Wordpress, Serendipity und Dokuwiki, sind Plugins verfügbar; außerdem wird eine Beispiel-Implementierung in PHP bereitgestellt, die sich als Vorlage für eigene Plugins verwenden lässt.

In diesem Blog verwende ich die Vernetzungsfunktion bereits seit vielen Jahren; gerne hätte ich eine solche Funktion auch für meine privaten Webseiten gehabt. Nach deren Relaunch war ich dann motiviert genug, mir diese Möglichkeit zu schaffen. Theoretisch sollte das nicht schwer sein: nanoc, mein static site generator, unterstützt das Konzept von Filtern, die (bspw.) aus Markdown HTML machen. In gleicher Weise lässt sich die Vernetzungsfunktion einbinden. Einziges Problem: die Beispiel-Implementierung ist in PHP gehalten, Varianten in Perl und ASP werden angeboten, aber ich bräuchte Ruby … und das “spreche” ich dazu noch kaum. Dennoch: einen Versuch erschien es mir wert.

Und zu meiner Überraschung war es dann gar nicht so schwierig, das PHP-Beispiel in Ruby als nanoc-Filter nachzubauen: erst nur die Grundfunktion, dann - aufgrund der stark ansteigenden Compile-Zeiten - auch den optionalen Cache. Und schon habe ich einen Prototypen in Betrieb, der auf meiner Homepage alle Gesetzes- und Rechtsprechungszitate mit dejure.org verlinkt!

Interessenten können sich den Filter auf meiner Homepage herunterladen.

Bootstrap mit nanoc

nospam@example.com (Thomas Hochstein) — Fri, 05 May 2017 15:15:00 +0000

Unter anderem für den Relaunch meiner Homepage habe ich mich damit beschäftigt, wie ich das CSS-Framework Bootstrap am besten mit nanoc, meinem bevorzugten static site generator, zur Anwendung bringen kann.

Bootstrap bringt einen ganzen Haufen CSS, etwas Javascript und Glyphicon Halflings als Webfont mit. Webfont und Javascript können unverändert bleiben, das CSS hingegen sollte aus den LESS-Dateien kompiliert werden, um so mit wenigen Anpassungen in variables.less das Aussehen der Website zu personalisieren.

Meine nanoc-Quelldateien habe ich dementsprechend folgendermaßen strukturiert:

content/
 :
 :--bootstrap/
 :   :
 :   :--js/
 :   :
 :   :--fonts/
 :   :
 :   :--less/
 :    
 :--res/
     :
     :--css/
     :
     :--fonts/
     :
     :--js/

In content/bootstrap/js/ landet das Javascript aus Bootstraps dist/js/, in content/bootstrap/fonts/ die Schriften aus dist/fonts/, und die Dateien aus less/ kommen nach content/bootstrap/less/. Dabei müssen jedenfalls in meiner alten Version 3 von nanoc noch einige Dateien umbenannt werden, weil sich nur in der Endung unterscheiende Dateien unzulässig sind: aus bootstrap.min.js wird so bootstrap-min.js, bei den Schriftdateien wird die Endung auch in den Dateinamen übernomme, so dass aus glyphicons-halflings-regular.ttf dann glyphicons-halflings-regular-ttf.ttf wird.

Der Inhalt von content/bootstrap/js/ landet dann beim Kompilieren in content/res/js/, derjenige von content/bootstrap/fonts/ unter Entfernung der “doppelten” Endungen in content/res/fonts/, und aus content/bootstrap/less/bootstrap.less wird (unter Einbindung aller anderen LESS-Dateien) content/res/css/bootstrap.css kompiliert.

Fertig.

In den Rules sieht das dann ungefähr so aus:

#!/usr/bin/env ruby

#########################
### compilation rules ###
#########################

# compile Bootstrap CSS (only) from bootstrap.less
compile '/bootstrap/less/bootstrap' do
  filter :less
end
compile '/bootstrap/*' do
  nil
end

# main rule
compile '*' do
  [...]
end

#####################
### routing rules ###
#####################

# copy font files and move last -XXX to extension
route '/res/fonts/*/' do
  # /bootstrap/fonts/foo-eot/ -> /res/fonts/foo.eot
  item.identifier.sub('/bootstrap/less/','/res/css/').sub(/-[^-]+\/$/, '') + '.' + item[:extension]
end

# copy bootstrap files
route '/bootstrap/less/bootstrap' do
  item.identifier.sub('/bootstrap/less/','/res/css/').chop + '.css'
end
route '/bootstrap/less/*' do
  nil
end
route '/bootstrap/*/' do
  item.identifier.sub('/bootstrap/','/res/').chop + '.' + item[:extension]
end

# main rule
route '*' do
  [...]
end

Es geht sicherlich einfacher und weniger komplex, aber so geht es jedenfalls auch.

Wenn man in seinem Git-Repository auch direkt einen bootstrap-Branch anlegt, kann man Bootstrap-Updates dort einspielen und in der Regel durch ein einfaches git checkout master; git merge bootstrap für die eigenen Seiten übernehmen.

nanoc 4.0.0 beta 1

nospam@example.com (Thomas Hochstein) — Mon, 18 May 2015 05:37:02 +0000

Bereits mehrfach hatte ich über nanoc berichtet, dessen Entwicklung nunmehr wieder mit Elan fortschreitet.

Seit einigen Tagen gibt es die erste Beta-Version von nanoc 4.0 mit bereits teilweise angepasster Dokumentation - und obwohl dieses Release eigentlich keine neuen Features enthalten, sondern nur den Code für zukünftige Veränderungen vorbereiten soll, gibt es einige Neuigkeiten zu vermelden:

In den Rules können nunmehr erweiterte Platzhalterzeichen (Globs) verwendet werden. Gab es bisher nur die Möglichkeit, * und + zu verwenden, bspw. in der Form /projects/*/, gibt es in nanoc 4.0 neue Möglichkeiten wie * contra ** oder Zeichensätze wie [abcdefg] oder auch Auswahllisten wie {foo,bar}. Vermutlich wird das der neue Default.
Von manchem lange erwartet gibt es in der neuen Version zwei verschiedene Formate für Items, also einzelne Quelltextdateien: full format (neu) und stripped format.

Traditionell wurden Quelltext-Dateien in nanoc durch ihren Namen ohne Erweiterung identifiziert, die Datei /projekte/2015/arche.md im Verzeichnis content konnte mithin als /projekte/2015/arche/ angesprochen werden. Da nanoc - ohne Änderungen an den Rules - standardmäßig aus jeder Quelltext-Datei ein Verzeichnis deren Namen und einer index.html erzeugte, also aus dem Quelltext /projekte/2015/arche.md die Datei /projekte/2015/arche/index.html wurde, die als http://example.com/projekte/2015/arche/ aufgerufen werden kann und soll, war das durchaus konsequent. Es verlangte vom Neubenutzer aber einiges an Eingewöhnungsaufwand und hatte vor allem den Nachteil, dass es keine Quell-Dateien geben durfte, die sich nur in der Erweiterung unterscheiden: die Dateien glyphicons-halflings-regular.ttf und glyphicons-halflings-regular.svg, um mal ein Beispiel aus der Praxis zu wählen, durfte es nicht nebeneinander im selben Verzeichnis geben.

Nunmehr gibt es stattdessen auch die Möglichkeit, Identifier für Items in ungekürzter Form zu erzeugen. Die Datei /projekte/2015/arche.md hat für nanoc dann nicht mehr den Identifier /projekte/2015/arche/, sondern /projekte/2015/arche.md. Das hat mehrere Vorteile: es ist einfacher zu verstehen, in Rules können nunmehr ohne Verrenkungen Dateien mit bestimmten Endungen referenziert werden, und es dürfen Dateien mit identischen Namen, aber unterschiedlichen Endungen vorkommen. Bei der Generierung von Zieldateien mit anderer Endung (meistens ja .html) hilft dann die neue Methode @item.identifier.without_ext, die für /projekte/2015/arche.md entsprechend /projekte/2015/arche zurückliefert, also wie gewohnt, nur ohne abschließenden /.

Benötigt(e) man mit dem stripped format zur Umwandlung von Markdown-Quelltexten in HTML ein Konstrukt wie

compile ‘*’ do
if item[:extension] == ‘md’
filter :kramdown
end
end

genügt nunmehr mit dem neuen full format ein einfaches

compile ‘/**/*.md’ do
filter :kramdown
end

Einen - mehr oder weniger großen - Nachteil hat das full format aber: es kann bei den Items - prinzipbedingt - das Konzept von “Eltern” und “Kindern” nicht mehr geben. Mit dem stripped format war klar, dass das Element /projekte/2015/arche/ ein Kind von /projekte/2015/ ist, und dieses wiederum ein Kind von /projekte/. Mit dem full format können aber “oberhalb” von /projekte/2015/arche/ die Dateien /projekte/2015.md und /projekte/2015.css nebeneinander existieren, so dass die Frage nach dem “Eltern”-Element sich nicht mehr eindeutig beantworten lässt. Es gibt also keine Baumstruktur der Elemente mehr - das kann u.a. die Erzeugung einer Navigation auf die bisher übliche Weise unmöglich machen.

Insgesamt bin ich aber auf nanoc 4.0 und vor allem dann die folgenden Versionen sehr gespannt!

(Für das Upgrade von nanoc 3.x auf nanoc 4.0 gibt es natürlich einen Upgrade Guide.)

nanoc und MySQL

nospam@example.com (Thomas Hochstein) — Thu, 30 Apr 2015 06:26:00 +0000

Ein static site generator wie bspw. nanoc erzeugt, wie der Name schon sagt, im wesentlichen statische Seiten ohne - zumindest serverseitige - dynamische Elemente, oder schlicht: HTML-Dateien. Dennoch ist es möglich, solchen Webpräsenzen eine begrenze “Dynamik” zu verleihen, und dies nicht nur durch Einbindung von Drittanbieter-Diensten wie bspw. der Kommentar- und Diskussionsplattform Disqus - soll sich der Inhalt einer oder mehrerer Seiten ändern, müssen sie eben neu generiert werden.

Üblicherweise wird die Neugenerierung immer dann (manuell) veranlasst, wenn eine neue Seite oder ein neuer Beitrag (in einem statisch generierten Blog) verfasst oder ein bestehendes Quelldokument verändert worden ist. Jedoch kann eine Neugenerierung der Seiten auch angestoßen durch externe Ereignisse erfolgen. Man könnte bspw. immer dann, wenn ein neuer Beitrag eines bestimmten Accounts auf Twitter veröffentlicht wird, diesen Tweet in die Webseiten einbinden und dann die dadurch veränderten Seiten neu generieren - oder, bspw., einen RSS-Feed regelmäßig (täglich, stündlich, …) auslesen und bei einer Änderung die betreffenden Seiten der (eigentlich statischen) Webpräsenz neu generieren und auf diese Weise einen Newsticker einbinden, der allerdings nicht in Echtzeit “tickt”. Sehr häufig ist eine solche Echtzeit-Aktualisierung aber auch gar nicht nötig, weil sich Änderungen ohnehin nur in größeren Zeitabständen ergeben und es unschädlich ist, wenn sie mit einer gewissen Verzögerung angezeigt werden. So bindet bspw. der CCCS in seinen durch nanoc erzeugten Webseiten die Tweets des Accounts @cccs ebenso ein wie eine Übersicht der Blogbeiträge von Aktiven des Vereins. Die entsprechenden Daten werden in regelmäßigen Abständen ausgelesen, danach werden dann - wenn erforderlich - die betreffenden Webseiten neu erzeugt.

Die Dynamik lässt sich aber noch deutlich weiter treiben.

Dynamische Seiten sind regelmäßig mit einer Datenbank verknüpft. Blogsysteme und CMS beispielsweise speichern Beiträge, Metadaten, Kommentare usw. in einer Datenbank und erzeugen beim Aufruf des Blogs oder der Website daraus bedarfsgerecht HTML-Seiten, die dann angezeigt (und ggf. gecached) werden. Seiteninhalte, Blogeinträge oder Kommentare werden in der Datenbank gespeichert und (ggf. nach Prüfung) beim nächsten Aufruf der Website oder des Blogs dann angezeigt.

Auch nanoc lässt sich mit einer Datenbank als Datenquelle betreiben. Bei jedem Durchlauf von nanoc compile wird dann nicht nur geprüft, ob sich die Quelldateien der Webpräsenz verändert haben, sondern auch, ob sich die Inhalte der Datenbank geändert haben; in beiden Fällen werden dann, wenn sich diese Änderungen auf die anzuzeigenden Inhalte auswirken, die entsprechenden statischen Webseiten neu erzeugt. So ist es bspw. durchaus denkbar, ein Webinterface zu schreiben, mit dem Seiteninhalte und Templates erzeugt und bearbeitet werden können, aus denen dann nanoc fertige Webseiten erzeugt - quasi ein CMS. Oder man erzeugt seine Blogbeiträge nicht als einzelne Quelldateien in HTML, Markdown oder anderweitig, sondern schreibt sie über ein - beliebig komfortabel gestaltetes - Webinterface in eine Datenbank und lässt nanoc dann daraus das fertige Blog gestalten. In ähnlicher Weise könnten so Informationen über Mitarbeiter (Rufnummer, Erreichbarkeit, Zuordnung zu Arbeitsbereichen) für eine Firmenwebsite oder Profile von Mitgliedern einer Gruppe oder eines sozialen Netzwerks in einer Datenbank gehalten und die - statische - Website bei Änderungen neu erzeugt werden.

Diese Vorgehensweise kann immer dann sinnvoll sein, wenn die Inhalte größtenteils statisch sind und/oder sich in eher größeren Abständen ändern. Werden in einem Blog in der Woche ein oder zwei Beiträge verfasst, wäre es überhaupt kein Problem, zwei- oder dreimal pro Woche eine ansonsten statische Website neu zu erzeugen; und Daten von Mitarbeitern oder Mitgliedern oder auch die einzelnen Seiten einer größeren Webpräsenz ändern sich zumeist eher seltener. Erforderlich ist letztendlich nur, dass entweder in regelmäßigen Abständen - per cron - geprüft wird, ob sich Änderungen an den Inhalten in der Datenbank ergeben haben, so dass die Website neu erzeugt werden muss, oder mit dem Speichern (oder der Freigabe) einer Änderungen automatisch einen Rebuild anzustoßen und die Website dann auch in die Echtumgebung zu übertragen (“Deployment”).

Die eigentliche Anbindung der Datenbank als Datenquelle an nanoc ist recht einfach gelöst und in der Dokumentation in Form eines nachvollziehbaren Beispiels bzw. Tutorials - mit sqlite, aber die Anpassung an MySQL ist trivial - unter der Überschrift “Using external sources” dargestellt. Einige kleinere Lücken der Darstellung, die einer 1:1-Umsetzung des Beispiels per copy & paste entgegenstanden, habe ich demletzt geschlossen.

In diesem Beispiel wird aus jedem Datensatz (Row) in der Datenbank(tabelle) ein Item in nanoc erzeugt, bei dem (nur) die Felder des Datensatzes (Columns) und deren Inhalte als Attribute übergeben werden - vergleichbar einer Quellcodedatei, die nur Metadaten in YAML enthält. Stattdessen könnte man natürlich auch direkt anzeigbare Seiten (im Beispiel Informationsseiten für jeden Mitarbeiter) erzeugen, indem ein Template mit den Daten befüllt wird; oder man übernimmt einen Feldinhalt aus der Datenbank als Seiteninhalt, bspw. für einen Blogpost. Die Möglichkeiten sind fast unbegrenzt. Die Datenbankinhalte lassen sich dann über ein anderes, geeignetes Interface - bspw. eine Webanwendung in PHP oder anderen Sprache - bearbeiten.

Ich habe bei der Erstellung von d-e-n.net auf diese Weise für die “Schreiberliste” die ohnehin schon in Form einer MySQL-Datenbank vorhandenen Inhalte der Profile der einzelnen Teilnehmer ausgelesen und erzeuge - derzeit in einem zweiten Schritte - daraus dann die Profilseiten, und natürlich die Übersicht der eingetragenen Teilnehmer. Ich bin aber sicher, dass sich die Profilseiten auch unmittelbar beim Auslesen der Datenbank erzeugen lassen, ohne den Umweg über (nicht compilierte, weil bis auf Metadaten leere) Items unter /_external/db/* zu gehen.

Das werde ich bei Gelegenheit dann einmal ausprobieren.

nanoc: Auswahl des Templates via YAML

nospam@example.com (Thomas Hochstein) — Wed, 29 Apr 2015 05:26:00 +0000

Nicht selten lassen sich die meisten Seiten einer Webpräsenz aus demselben Template erzeugen, wohingegen einige Ausnahmefälle einer Sonderbehandlung bedürfen - bspw. die Startseite oder landing page, die oft anders gestaltet ist als der Rest der Webseiten, und sei es nur, dass sie keine oder andere Navigations-Elemente aufweist oder mehrspaltig statt einspaltig (oder umgekehrt) dargestellt werden soll.

Mag es bei der Verwendung von nanoc für eine singuläre Ausnahme noch sinnvoll sein, sie explizit in die - bereits erläuterte - Rules-Datei aufzunehmen, gibt es für diese Aufgabenstellung eine sehr einfache Lösung: ein abweichendes Template kann nämlich im YAML-Metadatenblock jeder Seite angegeben werden.

Sollen nun die Webseiten einer Präsenz normalerweise das Template namens default verwenden, die Startseite aber das Template startpage, so erhält die Quellcode-Datei der Startseite einen entsprechenden Eintrag in ihre YAML-Metadaten, bspw. template: startpage, und die Rules-Datei erhält dann im compile-Block an der passenden Stelle - statt layout 'default' - die Anweisung layout item[:template] || 'default'.

Man kann auch - wie es der CCCS tut - die Variante “gar kein Template” direkt mit aufnehmen:

if item[:template]!='none'
  layout item[:template] || 'default'
end

nanoc-Rules "passthrough" und "ignore"

nospam@example.com (Thomas Hochstein) — Fri, 24 Apr 2015 05:12:17 +0000

Ich nutze mittlerweile für eine ganze Reihe (meist eher einfacher) Webpräsenzen den static site generator nanoc. nanoc, geschrieben in Ruby, erzeugt anhand vorgegebener Regeln aus einer Verzeichnisstruktur mit Quellcode-Dateien in verschiedenen denkbaren Formaten und Seiten-Templates unter Anwendung von Filtern und ggf. ergänzenden (in Ruby geschriebenen) Modulen eine (grundsätzlich) statische, d.h. aus einzelnen HTML-Dateien bestehende, Website. Man kann sich das beispielsweise an den Webseiten des CCCS ansehen.

Regeln in der `Rules`-Datei

Die Datei Rules enthält dabei die Regelsätze, nach denen die fertigen Webseiten erzeugt werden. Dabei gibt es verschiedene Arten von Regeln, die der Reihe nach von oben nach unten abgearbeitet werden; die Einzelheiten finden sich in der nanoc-Dokumentation unter Basics zusammengefasst.

`preprocess`-Block

Zunächst kann ein optionaler preprocess-Block definiert werden, in dem Funktionen zusammengestellt werden können, die vor der Bearbeitung der einzelnen Quellcode-Dateien ausgeführt werden sollen. Dieser Block wird - als Code - ausgeführt, sobald die Datenstrukturen geladen wurden.

`compile`-Regeln

Danach folgen compile-Regeln, die jeweils definieren, welche Filter auf welche Quellcode-Dateien (oder allgemeiner: Items) angewendet werden sollen und in welches Template sie eingefügt gehören. So kann bspw. Markdown AsciiDoc in HTML umgewandelt werden, LESS oder SASS compiliert werden usw. usf. Zu Beginn jedes Regelsatzes ist definiert, auf welche Items er angewendet werden soll; am Ende steht normalerweise eine Default-Regel, die alle nicht gesondert definierten Fälle “erschlägt”. Die Regeln werden der Reihe nach abgearbeitet und die erste zutreffende Regel wird ausgeführt.

Die bei der Erzeugung einer neuen Site erstellte Beispiel-Rules sehen insoweit folgendermaßen aus:

compile ‘*’ do
if item[:extension] == ‘css’
# don’t filter stylesheets
elsif item.binary?
# don’t filter binary items
else
filter :erb
layout ‘default’
end
end

.css-Dateien und binäre Dateien werden also gar nicht verarbeitet, alle anderen Dateien werden als HTML mit embedded Ruby aufgefasst und mit dem Default-Template versehen.

`routing`-Regeln

Nach der Erzeugung der Items entscheiden die routing-Regeln, wo die erzeugten Dateien gespeichert werden. Standardmäßig wird aus jeder Quelldatei ein Verzeichnis mit einer entsprechenden index.html erzeugt; so wird aus dem Markdown-Quellcode .../faqs/usenet/zitieren.md die fertige HTML-Datei .../faqs/usenet/zitieren/index.html, so dass die Webseite dann unter http://domain.example/faqs/usenet/zitieren/ aufrufbar ist. Das kann so natürlich nicht für .css-Dateien oder Downloads gelten.

Die Beispiel-Rules sehen hier dementsprechend so aus:

route ‘*’ do
if item[:extension] == ‘css’
# Write item with identifier /foo/ to /foo.css
item.identifier.chop + ‘.css’
elsif item.binary?
# Write item with identifier /foo/ to /foo.ext
item.identifier.chop + ‘.’ + item[:extension]
else
# Write item with identifier /foo/ to /foo/index.html
item.identifier + ‘index.html’
end
end

`layout`-Regeln

Auch die Templates selbst müssen oft noch compiliert werden, bestehen sie doch nicht aus reinem HTML, sondern regelmäßig aus einer Template-Sprache. Welches Template wie bearbeitet wird, regeln - nun ja - die layout-Regeln.

Standardmäßig sind embedded Ruby-Templates vorgesehen:

layout ‘*’, :erb

`Rules`-Dokumentation

Die Einzelheiten zu compile-, routing- und layout-Regeln lassen sich der nanoc-Dokumentation im Abschnitt “Rules” entnehmen.

Nicht dort benannt, aber an mancherlei anderen Stellen der Dokumentation angesprochen sind der preprocess-Block, aber auch die passthrough-Regeln. Die gleichfalls durch nanoc unterstützten ignore-Regeln finden außerhalb der Code- bzw. API-Dokumentation gar keine Erwähnung.

`passthrough`- und `ignore`-Regeln

Das ist schade, denn beide stellen eine praktische Abkürzung dar, wenn ein bestimmtes Item entweder ungefiltert und ohne Veränderung an seinem Namen und Pfad, also “as is”, durchgereicht werden oder wenn es gar nicht bearbeitet werden, sondern ignoriert werden soll.

`passthrough`

passthrough-Regeln finden in der Dokumentation unter der Überschrift “Troubleshooting” Erwähnung. Hat man alle seine .css-Dateien in einem bestimmten Verzeichnis gesammelt, bspw. in /assets/css, und will sie auch genau dort wiederfinden, kann man sie entweder von der Kompilation ausnehmen und unverändert routen, wie das (nur eben für Dateien mit der Endung .css statt Dateien in einem bestimmten Verzeichnis) bereits in den obigen Beispielen erfolgt:

route ‘/assets/css/*/’ do
item.identifier.chop + item[:extension]
end
compile ‘/assets/css/*/’ do
nil
end

Einfacher und kürzer geht es aber auch schlicht so:

passthrough ‘/assets/css/*/’

Das kopiert alle Dateien im Quellcode-Verzeichnis /assets/css/ unverändert in das Ausgabeverzeichnis ‘/assets/css/`.

`ignore`

ignore-Regeln wurden leider auch bei der Erstellung der Dokumentation ignoriert; dabei sind sie durchaus praktisch, kann man doch auf diese Weise Quellcode-Dateien von jeder Bearbeitung ausschließen und komplett ignorieren. Das ist insbesondere - und eigentlich nur - dann sinnvoll, wenn es sich um Dateien handelt, die ausschließlich Metadaten in Form von YAML front matter enthalten und daher nicht angezeigt werden sollen. Das Repository der CCCS-Webseiten enthält bspw. ein Verzeichnis _data mit .yaml-Dateien, in denen Termine pp. definiert werden, oder mit Templates zur Erzeugung von Aushängen oder Pressetexten (mit Hilfe von eigenen nanoc-Kommandos).

Will man also alle Dateien oder Verzeichnisse von einer Bearbeitung ausnehmen, die mit einem Unterstrich beginnen (und so bspw. auch Quellcode-Dateien temporär durch eine Umbenennung “ausblenden” können, ohne sie zu löschen), kann man entweder entsprechende compile- und routing-Regeln erzeugen:

compile %r{/_} do
nil
end
route %r{/_} do
nil
end

Oder man fasst sich kürzer und das in einer Regel zusammen, was nicht zuletzt auch der Übersichtlichkeit dient:

ignore %r{/_}