Hugo und docsy

Mit dem Docsy Hugo Theme können sich Projekt Maintainer und Website Betreiber auf den Inhalt konzentrieren, ohne jedesmal eine Website Infrastruktur komplett neu aufbauen zu müssen.
Von Clemens Kraus |
Categories:
Tags:

  3 Minuten Lesezeit  

Wer ist Hugo ;-)

Hier kann man lesen, wie das Blog erstellt wurde, mit welchen Tools und dass man das Ganze mit wenigen Anpassungen auch für andere Zwecke verwenden kann (Web-Sites, Dokumentationen etc.).

Aller Anfang ist leicht

Das Blog wurde mit dem Content Management System (CMS) bzw. Website Generator Hugo erzeugt, welcher auch statische HTML-Seiten generieren kann, die man einfach auf den Webspace seines Providers hochlädt.

Als Template wurde docsy eingesetzt, was eingentlich zur Dokumentation von Entwicklungsprojekten gedacht ist.

Wenn man sich nur ein wenig mit Hugo und Docsy beschäftigt, bekommt man dafür schon sehr schöne Ergebnisse.

Man darf das Pärchen Hugo/docsy aber nicht unterschätzen, denn es gibt sehr grosse Websites, die beide einsetzen - u.a. https://kubernetes.io.

Nachdem im Internet jede Menge an Dokumentation über Hugo/docsy zu finden ist, beschränke ich mich nur auf ein paar wenige Aspekte.

So sieht mein Setup aus

Ich habe mir das Docsy Beispiel docsy/docsy-example von github https://github.com/google/docsy-example heruntergeladen und - wie dort beschrieben - als Container erzeugt. Dazu ruft man

docker-compose build

auf. Danach startet man einfach den Container mit:

docker-compose up

Der Container heisst ebenfalls docsy/docsy-example. Wenn man im Browser dann

http://localhost:1313

aufruft, sieht man schon die Beispiel-Website.

Zurück zur Einfachheit

Manchen mag vielleicht die Verwendung einer Markdown-Sprache wie md abschrecken, mit der man den Inhalt im content-Verzeichnis erstellt, aber mir gefällt das Schreiben in dieser Sprache. Man ist relativ schnell und kann auch gleich das Ergebnis sehen, wenn man einen Markup-Editor wie z.B. ReText unter Linux verwendet.

Md wir auch viel in Entwicklungsprojekten und Entwicklungsumgebungen (Visual Studio) eingesetzt.

Wenn man schon etwas Development-Erfahrung gesammelt hat, fühlt man sich gleich heimisch, denn es können die gleichen Tools wiederverwendet werden, die man sonst zum Entwickeln einsetzt (Github, Pipelines …)

Gute Erweiterbarkeit

Es gibt ein paar verschiedene vordefinierte Layout-Blöcke im docsy-Template, die auf der Homepage und im “About”-Menu eingesetzt wurden.

Mit zwei Zeilen (“blocks/section”) hat man einen ganzen Bereich definiert (mit einer andere Farbe oder einem Hintergrundbild) und muss sich nicht mit den Feinheiten von HTML- oder CSS-Anweisungen auseinandersetzen.

{{% blocks/section type="section" color="primary" %}}
## Über den Inhalt
Mich interessiert, wie man **technische Komponenten** (PV-Anlage ...
{{% /blocks/section %}}

Man kann aber auch weitere Hugo-Module aktivieren, mit denen über ein paar Befehlszeilen Diagramme erzeugt werden, mathematische Formeln grafisch korrekt angezeigt werden oder sogar eine Mindmap mittels markup optisch sehr ansprechend dargestellt werden kann:

# markmap

## Links

- <https://markmap.js.org/>
- [GitHub](https://github.com/gera2ld/markmap)

## Related

- [coc-markmap](https://github.com/gera2ld/coc-markmap)
- [gatsby-remark-markmap](https://github.com/gera2ld/gatsby-remark-markmap)

## Features

- links
- **inline** ~~text~~ *styles*
- multiline
  text
- `inline code`

Diese Map wird so im Text definiert:

# markmap

## Links

- <https://markmap.js.org/>
- [GitHub](https://github.com/gera2ld/markmap)

## Related

- [coc-markmap](https://github.com/gera2ld/coc-markmap)
- [gatsby-remark-markmap](https://github.com/gera2ld/gatsby-remark-markmap)

## Features

- links
- **inline** ~~text~~ *styles*
- multiline
  text
- `inline code`