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.

Die öffentliche MyCoRe-Dokumentation ist Teil der Webseite mycore.org und wird mit Hugo erstellt
/documentation/.
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.
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.

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