Guidedog / Dokumentation 0.2.0

Vorlagen¶

Eine Vorlage bestimmt die Darstellung, ohne den Quelltext zu duplizieren. Guidedog verwendet Jinja für HTML und Typst für PDF.

Guidedog-Vorlagen sind sichtbare, bearbeitbare Projektdateien. guidedog quickstart legt die tatsächlich verwendeten Vorlagen direkt im Projekt an:

_templates/layout.html definiert die HTML-Struktur mit Jinja.
_templates/book.typ definiert PDF-Layout, Typografie und Titelseite mit Typst.
_static/guidedog.css und _static/guidedog.js liefern Standardstile und Browserfunktionen.

Vorlagen liegen im Projekt, nicht in externen Paketen oder Binärcaches. Nach dem Bearbeiten bauen Sie mit guidedog build neu und prüfen mit guidedog serve.

HTML-Vorlagen¶

Guidedog rendert layout.html mit der eingebauten Jinja-Engine. Das Layout kann in Teilvorlagen, Makrobibliotheken und mehrere Vererbungsstufen gegliedert werden.

Modulare Vorlagenstruktur¶

Vorlagen können beliebig auf Dateien und Unterordner in templates_path verteilt werden. Standard ist ["_templates"]:

my-docs/
├── conf.toml
├── index.rst
└── _templates/
    ├── layout.html
    ├── base.html
    ├── partials/
    │   ├── header.html
    │   ├── navigation.html
    │   ├── searchbox.html
    │   └── footer.html
    └── macros/
        └── components.html

Guidedog durchsucht Dateien und Unterordner in templates_path. Include- und Importpfade sind relativ zu diesen Ordnern:

Listing 1 _templates/layout.html¶

{% extends "base.html" %}

{% block header %}
  {% include "partials/header.html" %}
{% endblock %}

{% block footer %}
  {% include "partials/footer.html" %}
{% endblock %}

Jinja-Makros können in separaten Dateien definiert und bei Bedarf importiert werden:

Listing 2 _templates/macros/components.html¶

{% macro badge(label, type="info") %}
  <span class="badge badge-{{ type }}">{{ label }}</span>
{% endmacro %}

Listing 3 Makros in Vorlagen verwenden¶

{% import "macros/components.html" as ui %}
{{ ui.badge("New", type="success") }}

Themenvererbung mit `!layout.html`¶

Für Änderungen an einzelnen Themenbereichen genügt die Vererbung des eingebauten Layouts mit der Ausrufezeichensyntax von Sphinx:

Listing 4 _templates/layout.html¶

{# Inherit Guidedog's built-in layout #}
{% extends "!layout.html" %}

{# Inject custom metadata or web fonts into the document head #}
{% block extrahead %}
  {{ super() }}
  <link rel="stylesheet" href="{{ pathto('_static/custom.css', 1) }}">
{% endblock %}

{# Replace or extend the footer with custom content #}
{% block footer %}
  {% include "partials/footer.html" %}
{% endblock %}

{% extends "!layout.html" %} oder {% extends "basic/layout.html" %} lädt die Themenvorlage, statt die eigene _templates/layout.html rekursiv zu laden.

{{ super() }} gibt in einem überschriebenen Block den Elterninhalt aus. So lassen sich Ergänzungen davor oder danach einfügen.

Layoutblöcke¶

Das eingebaute layout.html definiert Blöcke nach den Sphinx-Konventionen:

Block	Aufgabe
`doctype`	Dokumenttypdeklaration; Standard ist `<!DOCTYPE html>`.
`htmltitle`	Das `<title>`-Element in `<head>`.
`linktags`	Navigations- und Metalinks: `favicon`, `index`, `search`, `prev` und `next`.
`css`	Stylesheetlinks und eingebettete CSS-Wurzelvariablen.
`scripts`	JavaScript-Tags für Suche und interaktive Funktionen.
`extrahead`	Einfügepunkt am Ende von `<head>` für Schriften, Analyse und Metatags.
`header`	Kopfbereich direkt vor der Hauptnavigation.
`relbar1`	Obere Navigation mit Marke, Version, Suche und Themenwechsel.
`rootrellink`	Einfügepunkt vor verwandten Links.
`relbaritems`	Eigene Elemente in der Navigationsleiste.
`sidebar1`	Container der linken Navigationsleiste.
`sidebartoc`	Inhaltsbaum in `sidebar1`.
`breadcrumbs`	Hierarchischer Navigationspfad über dem Artikel.
`document`	Container um den Seiteninhalt.
`body`	Gerenderter HTML-Inhalt des Dokuments: `{{ body }}`.
`relbar2`	Untere Navigation zum vorherigen und nächsten Kapitel.
`footer`	Seitenfuß mit Urheberrecht, Aktualisierungszeitpunkt und Quelllinks.
`sidebar2`	Rechte Zusatzleiste mit der Seitengliederung.

Vorlagen finden¶

Guidedog durchsucht templates_path aus conf.toml der Reihe nach, danach die eingebauten Vorlagen. Vorlagennamen sind relative Pfade; .. darf nicht aus diesen Ordnern führen.

Alle Dateien und Unterordner in templates_path sind Buildabhängigkeiten. guidedog build und guidedog serve erkennen hinzugefügte, geänderte und entfernte Vorlagen und rendern die Website neu.

Seitenvariablen¶

Wo Sphinx einen Variablennamen vorgibt, verwendet Guidedog denselben. So lassen sich Teile von Sphinx-Themes übernehmen.

Variable	Wert
`body`	Das Dokument als HTML.
`title`	Der Dokumenttitel.
`pagename`, `docname`	Der Dokumentname, etwa `usage/install`. Auf Seiten ohne Dokument ist `docname` leer und `pagename` enthält wie bei Sphinx den Seitennamen: `genindex`, `py-modindex`, `search` oder den Namen einer Vorlagenseite.
`toc`	Die aus Toctrees erzeugte Navigation als HTML.
`outline`	Die eigenen Abschnitte des Dokuments als HTML; leer, wenn keine vorhanden sind.
`prev`, `next`	Die Nachbarseiten in Lesereihenfolge mit `url` (auch `link`) und `title`; an den Enden keine.
`project`, `version`, `release`, `copyright`, `language`	Die gleichnamigen Einstellungen.
`html_title`, `docstitle`	`html_title`, standardmäßig „<project> <release> documentation“.
`html_short_title`, `shorttitle`	`html_short_title`.
`root_doc`, `master_doc`	Der Name des Wurzeldokuments.
`pathto_root`	Der Pfad von der Seite zum Site-Stamm, etwa `../`.
`root_url`, `search_url`, `genindex_url`	Links zu Wurzelseite, Suchseite und allgemeinem Index.
`css_files`, `js_files`	Dateilisten mit `url`: zuerst Guidedogs Dateien, dann `html_css_files` und `html_js_files`.
`logo_url`, `favicon_url`	`html_logo` und `html_favicon` unter `_static`; leer, wenn nicht gesetzt.
`accent`	`html_theme_options.accent`, die Theme-Farbe.
`sourcelink_url`	Die Dokumentquelle unter `_sources`, falls angezeigt; sonst leer.
`last_updated`	Das Build-Datum gemäß `html_last_updated_fmt`, falls gesetzt; sonst leer.
`show_copyright`, `show_sphinx`, `show_guidedog`, `has_source`, `show_source`	Die Einstellungen `html_show_*` und `html_copy_source`.
`builder`, `file_suffix`	Der Buildername, etwa `html`, und das Seitensuffix.
Jeder Schlüssel von `html_context`	Der Wert behält seinen Typ wie bei Sphinx: `false` ist in `{% if %}` falsch, Zahlen bleiben Zahlen, Arrays werden Listen, Tabellen Wörterbücher in der Schlüsselreihenfolge von `conf.toml`. `guidedog migrate` übernimmt literale Einträge aus `html_context` in `conf.py`. Berechnete Werte bleiben undefiniert und gelten in Vorlagen als falsch.

pathto ist die Sphinx-Vorlagenfunktion. pathto("usage/install") gibt die Dokument-URL, pathto("_static/logo.svg", 1) eine Datei-URL unter der Websitewurzel zurück, jeweils relativ zur aktuellen Seite. Bei singlehtml wird ein Dokument zum Abschnitt: Der erste Aufruf ergibt dort #document-usage-install, auf Index- und Suchseiten index.html#document-usage-install. Nichtdokumentnamen wie genindex oder Vorlagenseiten liegen bei allen Buildern an der Websitewurzel.

Aus Vorlagen erzeugte Seiten¶

html_additional_pages erzeugt wie Sphinx Seiten allein aus Vorlagen. Jeder Schlüssel ist ein Seitenname, jeder Wert eine Vorlage in templates_path:

Listing 5 conf.toml¶

root_doc = "contents"

[html_additional_pages]
index = "indexcontent.html"
download = "download.html"

Eine Seitenvorlage erweitert gewöhnlich layout.html und füllt dessen Blöcke, damit sie wie die übrigen Seiten aussieht:

Listing 6 _templates/indexcontent.html¶

{% extends "layout.html" %}
{% block htmltitle %}<title>{{ shorttitle }}</title>{% endblock %}
{% block body %}
  <h1>{{ docstitle|e }}</h1>
  <p><a href="{{ pathto("tutorial/index") }}">Tutorial</a></p>
{% endblock %}

Die Vorlage erhält Variablen einer Seite ohne Dokument: pagename ist der Name (index), title und body sind leer. pathto, toc, toctree() und html_context funktionieren normal. html, dirhtml und singlehtml schreiben sie bei jedem Build als <name>.html (html_file_suffix) an die Wurzel. Änderungen an beliebigen Dateien in templates_path bauen alle Seiten neu.

Die Platzierung der Seite und Unterschiede zu Sphinx:

Eine gleichnamige Seite ersetzt die Dokumentseite, wie bei Sphinx durch späteres Schreiben. index = "landing.html" macht index.html zur Landingpage; index.rst liefert weiterhin das Inhaltsverzeichnis. Bei singlehtml bleibt die Einzelseite; die Vorlagenseite wird mit Warnung ausgelassen.
dirhtml schreibt download.html neben genindex.html und search.html, während Sphinx download/index.html schreibt. pathto("download") verweist auf diese Datei.
Der Name muss eine Datei an der Websitewurzel bezeichnen. "sub/page" wird mit build.additional_page abgelehnt, da Links von der Wurzel ausgehen. Bereits belegte Namen wie genindex werden ebenfalls abgelehnt; Sphinx würde eine der Seiten überschreiben.
guidedog migrate übernimmt html_additional_pages aus conf.py.

Fehler¶

Ein Vorlagenfehler stoppt den Build und zeigt Datei, Zeile, Quelltext und Korrekturhinweis:

TEMPLATE ERROR                                                  template.error

  _templates/base.html:1

No filter named 'defualt'.

Did you mean the filter 'default'?

Eine nicht definierte Variable wird wie in Jinja leer ausgegeben.

Ausufernde Vorlagen stoppen mit Fehler statt Absturz: bei mehr als 100 Syntaxebenen (Klammern, Tags, Operator-, Filter- oder elif-Ketten), mehr als 200 Makro-, Include- oder rekursiven Schleifenebenen oder über 512 KiB Rekursionsstack. Eine Liste, die sich selbst enthält, erscheint wie in Python als [...].

PDF-Vorlagen¶

Das PDF-Buch wird mit Typst gesetzt. _templates/book.typ ist eine normale Typst-Datei mit einer book-Funktion. Guidedog schreibt den Buchquelltext folgendermaßen:

#import "/_templates/book.typ": book
#show: book.with(title: ..., author: ..., version: ..., date: ...,
  lang: ..., paper: ..., numbering: ..., logo: ...)
// the chapters, one per document of the root toctree

Alles, was das Buch gestaltet, steht in dieser Datei: Schriften, Seitenmaß und Ränder, Überschriften, Titelseite, Kolumnentitel und Inhaltsverzeichnis.

Parameter¶

Parameter	Wert
`title`	`title` des Buchs in `pdf_documents`, andernfalls `project`.
`author`	`author` des Buchs, andernfalls die Einstellung `author`.
`version`	`release`.
`date`	`\|today\|`: `today`, falls gesetzt, sonst das Build-Datum gemäß `today_fmt`.
`lang`	`language`.
`paper`	`"a4"` oder `"us-letter"`, falls `pdf_paper_size` den Wert `letter` hat.
`numbering`	`true`, wenn ein Toctree die Option `numbered` hat.
`logo`	Der Pfad von `pdf_logo`; fehlt, wenn nicht gesetzt.
`copyright`	`copyright` für das Kolophon; wird nur an eine Vorlage übergeben, die es annimmt.
`body`	Die Kapitel.

Vorlagen dürfen eigene Parameter mit Standardwerten ergänzen. Die quickstart-Vorlage hat accent, die Schriften serif, sans, mono, die Textgröße size und page-ref. Mit einer Funktion wie n => [p. #n] ergänzt Letzteres Seitenzahlen bei Querverweisen.

Modulare Typst-Vorlagen¶

Typst-Stile, Makros und Titelseiten können auf mehrere .typ-Dateien in _templates/ verteilt und mit #import und #include verbunden werden:

Listing 7 _templates/book.typ¶

#import "cover.typ": title-page
#import "typography.typ": apply-styles

#let book(
  title: "",
  author: "",
  version: "",
  date: "",
  lang: "en",
  paper: "a4",
  numbering: false,
  logo: none,
  body,
) = {
  apply-styles()
  title-page(title: title, author: author, version: version, logo: logo)
  body
}

Was eine Vorlage verwenden kann¶

Typst-Pakete

Pakete wie #import "@preview/cetz:0.4.2" werden beim ersten Einsatz heruntergeladen. pdf_packages = "offline" beschränkt den Build auf bereits vorhandene Pakete.

Schriften

Systemschriften sind wie beim Befehl typst verfügbar. Ergänzen Sie Ordner mit pdf_font_paths. pdf_fonts = "embedded" nutzt nur Typsts eingebaute Schriften für byteweise reproduzierbare Bücher.

Präambel

pdf_preamble benennt eine Typst-Datei nach #show: book, geeignet für einige set- und show-Regeln ohne eigene Vorlage.

Typst in einem Dokument

Dokumente sind reStructuredText und Markdown; Typst-Dateien sind keine Dokumente. Typst-Markup für das Buch kommt in einen Raw-Block, den Webseiten auslassen:

.. raw:: typst

   #align(center)[#text(size: 14pt)[Only in the book]]

.. only:: pdf beschränkt auch gewöhnliche Inhalte auf das Buch.

Typst-Fehler nennen Datei und Zeile, ob in Vorlage oder generiertem Buch. Jede PDF-Quelle liegt in _build/pdf/sources/<pdf-filename>.typ; für reference-en.pdf also sources/reference-en.pdf.typ. Ein Einzelbuch-Build behält auch _build/pdf/book-<language>.typ zur Prüfung. Bei Fehlern wird nichts veröffentlicht; die Quelle bleibt am genannten Pfad unter _build/.doctrees/failed. Mehrere Bücher erhalten getrennte Fehlerquellen.

Eine neue Vorlage schreiben¶

Beginnen Sie mit den von quickstart geschriebenen Vorlagen, die alle Teile zeigen:

Behalten Sie das von der Standard-CSS erwartete layout.html-Markup bei oder ersetzen Sie zugleich _static/guidedog.css.
Verschieben Sie wiederkehrende Teile in eigene Dateien und nutzen Sie include, oder erstellen Sie base.html und erben Sie in layout.html mit extends.
Für das Buch ändern Sie die Regeln von book oder schreiben eine neue Funktion mit gleichem Namen und gleichen Parametern.

Verwenden Sie beim Bearbeiten guidedog serve. Speichern Sie und laden Sie den Browser neu; der Server baut geänderte Eingaben vor der Auslieferung.