Dokumentation (mit Hugo)

Wichtiger Bestandteil eines Open-Source-Projektes ist die Dokumentation. An dieser Stelle werden die technische Basis vorgestellt, Konzepte und Regeln festgelegt sowie Hilfestellungen für die dokumentierenden Entwickler gesammelt.

Allgemeines

Die Dokumentation von MyCoRe und die Unterstützung der Entwickler erfolgt über mehrere Medien.

  1. Die öffentliche MyCoRe-Dokumentation ist Teil der Webseite mycore.org und wird mit Hugo erstellt
    https://www.mycore.de/documentation/.
  2. Die Know-How- und Dokumentationsseiten des MyCoRe-Wikis
    http://cmswiki.rrz.uni-hamburg.de/hummel/MyCoRe/Dokumentation
    unterstützen als Platform für ein Wissensforum den Erfahrungsaustausch der Anwender.
  3. Die Mailing-Listen für Benutzer und Entwickler dienen der direkten Kommunikation.

Webseite mit dem Static Site Genenerator Hugo

Im Frühjahr 2019 wurde die Dokumentation von Apache Forrest auf den Static Site Generator Hugo umgestellt.

Installation und Konfiguration

Die Installation und die ersten Schritte werden im Abschnitt Einrichtung beschrieben.

Verzeichnisstruktur

Die Verzeichnisstruktur folgt den Empfehlungen von Hugo (s. Hugo: Directory Structure).

config
enthält zentrale Konfigurationsdateien und Menüs für die unterstützten Sprachen.
content
enthält die eigentlichen Inhalte der Webseite (Textdateien).
Für jede Sprache (de, en) wurde ein eigener Ordner erstellt (s. Hugo: Translation by content directory). Unter dem Sprachcode io können Textentwürfe abgelegt werden. Diese können in der lokalen Hugo-Instanz gesehen und bearbeitet werden. Auf dem Server werden sie ausgeblendet.
public, resources
sind von Hugo generierte Verzeichnisse. public enthält die von Hugo generierte Webseite für das Deployment auf dem Server
static
enthält alle Dateien, die nicht durch Hugo verarbeitet werden sollen, z.B. Bilder, CSS und Javascript. Diese Dateien werden von Hugo unverändert übernommen.
themes
Für die MyCoRe-Dokumentation wurde ein eigenes Theme (s. Hugo: Themes) erstellt, in dem die allgemeine, Template- und Layoutdateien gekapselt werden. Die Struktur des Theme-Verzeichnisses (mycore-bootstrap) entspricht der Struktur des Hauptverzeichnisses.
target, pom.xml
von Maven benötigte Dateien
Statische Dateien für CSS- und Javascript-Frameworks werden per Maven-Build integriert und nicht ins Git-Repository eingecheckt.
README.md
enthält eine kurze Beschreibung für die Anzeige des mycore-website-Projektes auf Github..

Content-Bereich

Der Content wird in 3 Bereiche gegliedert. Dadurch können für diese verschiedene Templates und Layouts definiert werden.

blog
enthält die Texte für Blog-Beiträge und Nachrichten.
documentation
enthält die Texte für den Bereich Dokumentation. Diese werden gesondert gruppiert, damit sie individuell gestaltbar sind.
site
enthält die weiteren Bereiche der MyCoRe-Homepage (z.B. Download, Organisation)
_index.html
ist eine separate Datei für die MyCoRe-Startseite.

Struktur einer einzelnen Seite

Jede Webseite besteht aus einem Header- und einem Textbereich.
---
title: "Dokumentation zur MyCoRe Dokumentation"
description: "Wichtiger Bestandteil eines Open-Source-Projektes ist die Dokumentation. 
              An dieser Stelle werden die technische Basis vorgestellt, Konzepte und Regeln festgelegt
              sowie Hilfestellungen für die dokumentierenden Entwickler gesammelt."
author: 	 ['Jens Kupferschmidt', 'Kathleen Neumann', 'Robert Stephan']
mcr_version: ['2018.06']
date: 		 "2019-04-04"
draft:       false
---

<h2>Technische Basis: Hugo</h2>
<p>Im Frühjahr 2019 ... </p>

Headerbereich dieser Seite

Der Header (s. Hugo: Front Matter) wird in YAML-Syntax beschrieben und enthält folgende Properties:

title
der Titel der Seite, wird als <h1>-Überschrift auf der Webseite angezeigt.
description
eine kurze Beschreibung der Seite, wird im Kopfbereich der Seite angezeigt.
author
die wesentlichen Autoren der Seite (in YAML-Listen-Syntax).
mcr_version
optional: die MyCoRe-Version, in der die beschriebene Funktionalität eingeführt bzw. verwendet wird. Sie wird als Versions-Tag oben auf der Seite eingeblendet.
date
das Datum der letzten wesentlichen Änderung. Liegt das angegebene Datum in der Zukunft, wird die seite ohne weitere Hugo-Optionen erst an diesem tag sichtbar!
draft
ist draft auf true gesetzt, wird die Seite nur mit speziellen Hugo-Optionen sichtbar.

alle Seiten sichtbar machen: hugo server --buildDrafts --buildFuture

Für Blog- und News-Seiten gilt ein erweiterter Header. Dieser wird im Abschnitt News und Blog erläutert.