Navigation

Theme-Test

Viele Features und Beispiele

Diese 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:

theme-base-08, theme-base-09, theme-base-0a, theme-base-0b, theme-base-0c, theme-base-0d, theme-base-0e, theme-base-0f

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:

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:

$$ \left( \begin{array}{c} n \\ r \end{array} \right) = \frac{n!}{r!(n-r)!} $$
{{< 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:

$$\left( \begin{array}{c} n \\ r \end{array} \right) = \frac{n!}{r!(n-r)!}$$
```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.

[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]

Abb. 1: Ein UML-Diagramm

```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.

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
```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.