Theme-Test
Viele Features und BeispieleDiese Seite ist, wie das Theme selbst, Work in Progress!
Das Theme basiert auf Hyde von Mark Otto, das von Steve Francia für Hugo portiert und von mir unter der Haube stark angepasst und umstrukturiert wurde, um neue Features von Hugo zu implementieren.
Konfiguration
Farbschema
Wichtigster Anpassungspunkt für das Theme ist das verwendete Farbschema. Es kann in config.toml
gesetzt werden und die folgenden Werte annehmen:
Die Farbwerte folgen dabei base16, das auch für das Sourcecode-Highlighting als Stylesheet verwendet wird.
config.toml
In der config.toml
-Datei können neben den Standard-Eigenschaften wie etwa dem Titel folgende Eigenschaften festgelegt werden:
theme
: Theme-Farbe (siehe oben). Wirkt sich auf CSS, Farb-Meta-Tag und Cookie-Consent Farbgebung aus.description
: Wird in der Seitenleiste unter dem Titel angezeigt.minWordCountForToc
: Mindestanzahl an Wörtern, sodass, falls vorhanden, eine Table of Contents auf PCs und Laptops angezeigt wird. Standardwert ist 1000, kann im Frontmatter übersteuert werden (siehe unten).cookieConsent
: Auftrue
setzen, um Cookie-Meldung zu aktivieren. MitcookieConsentPolicyLink
kann der Link konfiguriert werden, mitcookieConsentMessage
die im Banner angezeigte Nachricht.piwik
: Auftrue
setzen, um Piwik/Matomo zu aktivieren. MitpiwikBaseUrl
undpiwikSiteId
kann die Einbindung konfiguriert werden. Alternativ wird Google-Analytics über die Hugo-Standard-Konfiguration ermöglicht.
Die folgenden Einstellungen werden zudem empfohlen:
DefaultContentLanguage = "de"
paginate = 5
preserveTaxonomyNames = true
pygmentsCodeFences = true
pygmentsuseclasses = true
[markup]
[markup.goldmark]
[markup.goldmark.extensions]
typographer = false
[markup.goldmark.renderer]
unsafe = true
[markup.tableOfContents]
endLevel = 2
startLevel = 1
[sitemap]
changefreq = "monthly"
priority = 0.5
filename = "sitemap.xml"
[taxonomies]
category = "categories"
series = "series"
audio = "audio"
[outputs]
home = ["HTML", "RSS", "JSON"]
[related]
includeNewer = true
[[related.indices]]
name = "date"
weight = 10
pattern = "2006"
[[related.indices]]
name = "categories"
weight = 100
[[related.indices]]
name = "series"
weight = 150
[[related.indices]]
name = "title"
weight = 150
[[related.indices]]
name = "subtitle"
weight = 150
Übersetzbarkeit ist zum jetzigen Zeitpunkt nicht integriert.
Anpassbarkeit mit SCSS
Über eine Datei assets/css/_custom.scss
kann selbst (S)CSS zu dem Theme hinzugefügt werden. Sie wird in der main.scss
des Themes als letztes importiert und ist standardmäßig leer.
Inhalte
Frontmatter für Artikel
Für normale Artikel wird ein YAML-Frontmatter nach folgendem Schema empfohlen:
title: "„Make America Great Again“"
subtitle: "Über die Wahlen in den USA – East Side Story, Teil 3"
date: "2016-11-05"
showSummary: true
categories: "Politik und Gesellschaft"
series: "East Side Story"
neologismus: "16-10"
resources:
- src : "trump.jpg"
name : "header"
params:
title: "Bild Trump"
link: "https://www.flickr.com/photos/nathancongleton/26535826426/"
author: "Nathan Congleton"
license: "by-nc-sa 2.0"
- src: "hillary.jpg"
params:
title: "Bild Clinton"
link: "https://www.flickr.com/photos/number7cloud/25664027770/"
author: "Lorie Shaull"
license: "by-nc-sa 2.0"
Das zusätzliche, optionale Feld subtitle
wird als Untertitel dargestellt. Sowohl categories
als auch series
können jeweils bis zu einen Wert beinhalten. Das Feld neologismus
beinhaltet den Code der Ausgabe des Neologismus, in dem der Artikel veröffentlicht wurde. Dieser Link wird unter dem Artikel dargestellt, gemeinsam mit dem endmatterText
und den automatisch erstellten Copyright-Angaben zu den Bildern innerhalb der resources
(aktuell werden nur CC-Lizenzen unterstützt). Das (optionale) Bild name: header
wird automatisch als Hero-Bild des Beitrags verwendet.
Wird der Parameter showSummary
auf true
gesetzt, wird auf der Startseite nur die Zusammenfassung der Seite angezeigt, die entweder automatisch generiert wird oder manuell definiert wird, indem der Artikel `
` verwendet. Ansonsten wird der volle Artikel dargestellt. Dieses Verhalten wurde gewählt, weil die automatisch generierten Zusammenfassungen von Hugo in der Regel schlecht sind.
Auf PCs und Laptops mit mehr als 1600px Breite wird automatisch ein Inhaltsverzeichnis angezeigt, wenn der Post mehr Wörter besitzt, als in der Site Config eingestellt ist (siehe oben). Mittels showToC
kann dieses Verhalten jedoch überschrieben werden.
Audio-Artikel aka Podcasts
Seit kurzem beinhaltet das Theme auch die Möglichkeit, Audio-Versionen der Artikel als Podcast einzubinden. Dafür muss im Frontmatter folgende Konfiguration hinzugefügt werden:
[params]
podcastDescription = ""
podcastCategory = ""
podcastSubCategory = ""
podcastImage = "podcast-icon.png"
Die Audio-Dateien werden dabei (wie Bilder) als Ressourcen zu den Artikeln eingebunden und im Frontmatter mit name: audio
und dem Parameter duration
konfiguriert:
audio: "posts"
resources:
- src: "1610 ESS3.mp3"
name: "audio"
params:
duration: "21:27"
Wie im obigen Ausschnitt dargestellt, muss zusätzlich der Parameter audio: posts
gesetzt werden, damit die Audio-Versionen zusätzlich auf einer Podcast-Liste unter der URL /audio/posts
auftauchen, die mit einer zusätzlichen _index.md
ergänzt werden kann:
---
title: Audio
---
<span style="display: inline-block; margin: 0 .3em .3em 0">Warum lesen, wenn man auch hören kann?</span> <a class="button" href="/audio/posts/index.xml" style="display: inline-block; float: right;">Podcast-Feed abonnieren</a></button>
<div style="margin-bottom: 4em"></div>
Shortcodes
Das Theme beinhaltet einige Shortcodes zum Layout komplexerer Inhalte. (Wegen der Limitationen im Rendering sind die Shortcodes in den Code-Beispielen jeweils mit zusätzlichen Leerzeichen versehen.)
Etwaig benötigter JavaScript wird nur geladen, wenn entsprechende Shortcodes auf einer Seite verwendet werden.
Abbildungen
Abbildungen funktionieren wie der normale figure
-Shortcode in Hugo. Wichtiger Unterschied: Die Bilder müssen in den resources
der Seite spezifiziert sein, es wird Lightbox2 verwendet, um eine Diashow der Originalbilder zu ermöglichen und die Bilder werden automatisch skaliert. Standardmäßig wird eine Breite von 300px verwendet, was zur Darstellung in der jeweiligen CSS-Klasse float-right
bzw. float-left
führt. Mit dem Parameter option
kann der Skalierbefehl .Resource
jedoch konfiguriert werden, etwa mit option="640x"
. Es wird außerdem ein srcset
verwendet, um bei Bedarf höher aufgelöste Bilder darzustellen. Hier kann mit optionX2
der Parameter konfiguriert werden. Wie in der Standard figure
wird die caption
mit markdownify
formatiert, was hier mittels markdownifyCaption="off"
abgeschaltet werden kann.
{{< figure src="img/2nf1.jpg" caption="I would walk 500 miles…" class="float-right" >}}
Photosets
Um größere Mengen an Bildern darstellen zu können, kann der photoset
-Shortcode wie folgt verwendet werden (mit vielen Eigenschaften von figure
):
{{< photoset >}}
{{< photoset-row >}}
{{< photoset-item src="img/amish.png" >}}
{{< photoset-item src="img/hopewell_out.png" >}}
{{</ photoset-row >}}
{{< photoset-row >}}
{{< photoset-item src="img/phili_small.png" >}}
{{< photoset-item src="img/liberty.png" >}}
{{</ photoset-row >}}
{{< photoset-row >}}
{{< photoset-item src="img/china.png" >}}
{{< photoset-item src="img/bay.png" >}}
{{</ photoset-row >}}
{{</ photoset >}}
Auch hier müssen die Bilder aus den resources
stammen, werden automatisch in eine Lightbox gepackt und skaliert. Außerdem werden die Bilder algorithmisch so dargestellt, dass jede Zeile stets die volle Breite einnimmt, wobei alle Bilder in der Zeile gleich hoch sind. Dabei wurde einem Tutorial von Coding Design gefolgt.
Mathematik
Das Theme unterstützt Mathematik in der aus LaTeX bekannten Notation, unterstützt durch KaTeX.
Der maths
-Shortcode inline:
\(\frac{a}{b}\)
{{< maths "\frac{a}{b}" />}}
Der maths
-Shortcode im als Block:
{{< maths >}}
\left(
\begin{array}{c}
n \\
r
\end{array}
\right) = \frac{n!}{r!(n-r)!}
{{</ maths >}}
Code Fences
Mathematik
Der maths
-Shortcode als Code Fences:
```latex
\left(
\begin{array}{c}
n \\
r
\end{array}
\right) = \frac{n!}{r!(n-r)!}
```
UML-Diagramme
Das Theme rendert UML-Diagramme mit nomnoml. Aktuell werden die Diagramme stets zentriert dargestellt. Ist der Parameter zoomable
gesetzt, wird durch Klicken das Diagramm auf voller Breite dargestellt. Als Indikator wird ein Lupen-Cursor angezeigt, ein etwaiges Inhaltsverzeichnis wird ausgeblendet.
Das Canvas wird in eine figure
gerendert, die mit den typischen Attributen wie caption
verwendet werden kann.
```nomnoml { caption="Abb. 1: Ein UML-Diagramm" }
[Pirate|eyeCount: Int|raid();pillage()|
[beard]--[parrot]
[beard]-:>[foul mouth]
]
[<abstract>Marauder]<:--[Pirate]
[Pirate]- 0..7[mischief]
[jollyness]->[Pirate]
[jollyness]->[rum]
[jollyness]->[singing]
[Pirate]-> *[rum|tastiness: Int|swig()]
[Pirate]->[singing]
[singing]<->[rum]
[<start>st]->[<state>plunder]
[plunder]->[<choice>more loot]
[more loot]->[st]
[more loot] no ->[<end>e]
[<actor>Sailor] - [<usecase>shiver me;timbers]
```
Sequenz-Diagramme
Dieses Theme unterstützt zudem alle Diagrammtypen von Mermaid, das insbesondere für Sequenzdiagramme sehr gut geeignet ist.
```mermaid
sequenceDiagram
participant User
participant SyncedSession
participant LocalSession
participant Local PouchDB
participant RemoteSession
participant Remote PouchDB
activate User
User->>+SyncedSession: login
SyncedSession->>+LocalSession: login
SyncedSession->>+RemoteSession: login
LocalSession->>+LocalSession: waitForFirstSync
RemoteSession->>+Remote PouchDB: login
Remote PouchDB-->>-RemoteSession: rejected
Note over RemoteSession: ConnectionState.rejected
RemoteSession-->>-SyncedSession: ConnectionState.rejected
SyncedSession->>LocalSession: set login and sync failed
Note over LocalSession: LoginState.loginFailed
Note over LocalSession: SyncState.failed
LocalSession->>-LocalSession: failure
LocalSession-->>-SyncedSession: LoginState.loginFailed
SyncedSession-->>User: LoginState.loginFailed
deactivate Session
deactivate User
```
Suche
Für die Suche werden lunr und mark.js verwendet. Die Suche kann auf einer beliebigen Seite (potentiell im meta
-Bereich der Website) über den parameterlosen search
-Shortcode eingebunden werden.