Theme-Pakete

Ein Theme-Paket ist eine einzige Datei, <name>.gsta.xz (Go-Slides Theme Archive): ein mit xz komprimiertes tar-Archiv (ustar oder pax) mit theme.hcl im Wurzelverzeichnis und den Dateien, die es deklariert. Es enthält das CSS eines Themes, Schriften, Logos und Hintergründe und, wenn gewünscht, Folien-Kinds, mit einem Namen, einer Version und einer Lizenz, sodass ein Theme weitergegeben und installiert werden kann. Theme-Pakete gibt es nach v0.17.1.

Die Datei theme.hcl

# theme.hcl
theme {
  name        = "acme"
  version     = "1.0.0"                 # semantic version
  description = "Example theme"
  authors     = ["go-slides contributors"]
  license     = "MIT"                   # SPDX expression
  homepage    = "https://go-slides.github.io"
  extends     = "default"               # the base theme, built in or installed
  min_slides  = "0.18.0"                # oldest go-slides it works with
}

css "theme.css" {}                      # in order; sha256 = "…" is optional

font "Roboto Mono" {
  weight  = 400                         # or "100 900"
  style   = "normal"
  file    = "fonts/RobotoMono-Regular.ttf"
  license = "OFL-1.1"                   # required for a font
}

asset "logo" { file = "assets/logo.svg" }

kind "acme-title" {                     # optional slide kinds
  class    = "lead"
  paginate = "false"
}

theme.hcl verwendet die native Syntax von HCL, nur mit Literalwerten: keine Funktion, keine Variable, kein file() und kein env(). Ein Name besteht aus Kleinbuchstaben, Ziffern und Bindestrichen und ist weder default noch gaia noch uncover. extends nennt das Basis-Theme; jeder css-Block fügt der Reihe nach ein Stylesheet hinzu; jeder font- und asset-Block nennt eine Datei des Pakets; jeder kind-Block ist ein Kind. Ein sha256 an einem css-, font- oder asset-Block wird beim Lesen des Pakets geprüft.

Das CSS verweist auf Schriften und Ressourcen über ihren Pfad im Paket, relativ zur CSS-Datei: background: url(assets/logo.svg). Beim Laden des Pakets wird jeder solche Verweis zu einer data:-URL, sodass die Seite in sich geschlossen ist, und ein font-Block wird zu einer @font-face. Ein Paket kann außerdem die Dateien LICENSE, NOTICE und README enthalten; jede andere Datei, die theme.hcl nicht deklariert, wird abgelehnt.

Packen, installieren und verwenden

slides theme pack dir       write dir/theme.hcl and its files as <name>.gsta.xz
slides theme verify file    run every check on a package
slides theme install file   check it, then install it for the current user
slides theme list           the installed packages
slides theme remove name

Installierte Pakete liegen in go-slides/themes im Konfigurationsverzeichnis des Benutzers (os.UserConfigDir(): ~/Library/Application Support, $XDG_CONFIG_HOME oder ~/.config, %AppData%). In einem Foliensatz:

---
theme: acme
---

findet ein installiertes Paket, nach den eingebauten Themes und --theme-set. --theme acme.gsta.xz und --theme-set acme.gsta.xz verwenden eine Datei direkt, ohne sie zu installieren; siehe Befehlszeile.

Die Kinds eines Pakets gelten mit --theme file.gsta.xz, mit --theme name für ein installiertes Paket oder mit theme: name im Front Matter eines Foliensatzes; die eigenen Kinds des Foliensatzes haben Vorrang.

Ein Paket ist eine nicht vertrauenswürdige Eingabe

Ein Theme-Paket kann von überall stammen; deshalb prüft jeder Leser (pack, verify, install, --theme, ein Build) es auf dieselbe Weise und lehnt es mit einem Fehler ab, der einen Code trägt (theme.archive, theme.limit, theme.meta, theme.css, theme.svg, theme.font, theme.checksum, theme.version):

• Archiv. Ein xz-Stream, dessen Wörterbuch begrenzt ist und dessen Fenster mit den Daten wächst. Im tar: kein .., kein absoluter Pfad, kein Laufwerksbuchstabe und kein Backslash in einem Namen; nur reguläre Dateien und Verzeichnisse (kein symbolischer oder harter Link, kein Gerät, keine FIFO); kein doppelter Name (ohne Beachtung der Groß- und Kleinschreibung verglichen); nur ustar- und pax-Header (keine GNU-Erweiterung, keine Sparse-Datei), ein pax-Header von höchstens 8 KiB. Größen sind das, was gelesen wird, nicht das, was ein Header angibt.
• Grenzen. Höchstens 16 MiB Archiv, 256 Einträge, 8 MiB je Eintrag, 24 MiB entpackt, ein xz-Wörterbuch von 16 MiB, ein entpackter Stream von höchstens dem 100-Fachen der Archivgröße (ab 64 KiB), theme.hcl höchstens 64 KiB und 32 Klammern tief, 1 MiB CSS je Datei, 4 MiB je Schrift oder Bild.
• CSS. Kein @import, kein @import-theme (verwenden Sie extends), kein image-set(), src() oder eine andere Funktion, die eine Ressource lädt, keine Backslash-Escape-Sequenz außerhalb eines Strings, kein </style. Ein url() ist ein #fragment, ein Bild oder eine Schrift mit data: oder eine deklarierte Datei des Pakets, nie eine Adresse, die das Paket verlässt.
• SVG. Kein script, kein foreignObject, kein Frame, kein embed, kein set, kein DOCTYPE und kein Event-Handler; ein href ist ein #fragment; kein url(), das die Datei verlässt.
• Schriften und Bilder werden geparst: Eine Schrift muss eine Schrift sein, ein Bild muss zu seiner Dateiendung passen, und für beide gilt eine Größengrenze.

Das Verzeichnis testdata/themes/acme des Repositorys ist ein kleines Beispiel.