nanoc-Rules "passthrough" und "ignore"
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</p>
- <p>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</p>
- <p>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{/_}
Kommentare
Ansicht der Kommentare: Linear | Verschachtelt
Thomas Hühn am :
nanoc wäre richtig anwenderfreundlich, wenn nicht die Sonderfälle wären.
Das klingt zunächst alles ganz toll, es spart ja auch drei Tastenanschläge!
Sobald man aber praktisch was machen will, was leicht außerhalb des üblichen liegt, kämpft man stundenlang.
Beispiel: https://groups.google.com/forum/#!topic/nanoc/a9m2GauDBlY
Häßlicher Workaround. Es hätte auch so schön straightforward sein können.
Thomas Hochstein am :
Es funktioniert nach meiner Erfahrung immer einfacher, wenn man versucht, sich nach den Strukturüberlegungen zu richten, die hinter einer Software stehen. Bei nanoc hilft es dementsprechend, wenn man - so glaube ich, allgemeinen Üblichkeiten folgend - CSS, JS, Bilder, Downloads pp. jeweils in eigene Verzeichnisse packt und ansonsten seine Quelltextdateien einfach logisch strukturiert und es hinnimmt, dass "quelltext.md" den Identifier "/quelltext" bekommt und als "/quelltext/index.html" ausgegeben wird. Das ist durchaus praktisch, weil dann Identifier ("/quelltext"/) und Aufruf im Browser ("http://example.com/quelltext/") identisch sind und alles einfach out of the box funktioniert.
Dein verlinktes Beispiel sollte - jedenfalls heute - mit den oben dargestellten Standard-Regeln, die automatisch installiert werden, komplett abgedeckt sein; Du bräuchtest nur eine Sonderregel für die robot.txt.
Thomas Hochstein am :
Vielleicht gefällt Dir dann übrigens nanoc 4.x besser: da soll sich insoweit einiges ändern …