HUGO

In the HUGO / HTML tab you generate markdown files according to HUGO and the relearn theme.

The conversion and adaptions are explained in a short tutorial: Video starten

For enumeration tables the content can be exported as explained in a short tutorial: Video starten

In the tab you can fix links in markdown files according to HUGO shortcodes.

The fixes for broken links are explained in a short tutorial: Video starten

The adaptions for links for HUGO as related references are explained in a short tutorial: Video starten

To map the files in the original links to new files in the documentation follow the steps shown in a short tutorial: Video starten

Installation of HUGO

Update des Themes

um das Theme auf die letzte Version zu bringen kann man den Befehl git submodule update --remote --merge themes/relearn verwenden

Übersetzung des Bestands an html

  • Übersetzung der *.html Seiten mit pandoc in *.md
  • Aufbau einer Ordnerstruktur die dem Index der chm Datei entspricht
  • Das Basisdokument der Ordner wird in die Ordner verschoben und in _index.md umbenannt
    • Dort im Frontmatter steht der Titel der im Menü angezeigt wird, e.g.: 
      --- 
title: Installation 
---

Überarbeitung der md Dateien

  • Korrektur der Bildverweise
    • Ordner mit den Bildern in den Ordner static kopieren
    • von e.g. ![](img/...) in ![](/manual/dwb/img/...)
    • ACHTUNG - Case sensitiv. Namen müssen stimmen
    • Icons gegebenenfalls freistellen für Darkmode
  • Entfernung aller störenden Formatierungsangaben
  • Entfernung der Kopfzeile (Überschrift wird von HUGO automatisch erzeugt)
  • Korrektur der internen Verweise
    • ändern von [![](/manual/dwb/img/VideoDE.svg?classes=inline)](http://media.snsb.info/Tutorials/dwb/Editing/OeffentlicheKontaktdaten.webm) zu [![Video starten](/manual/dwb/img/VideoDE.svg?height=20px&lightbox=false&classes=inline)](http://media.snsb.info/Tutorials/dwb/Editing/OeffentlicheKontaktdaten.webm)
      • ansonsten wird das Bild gezeigt statt das Video zu starten
    • ändern von 
      [Contact](Contact.htm)
      zu e.g. 
      [Contact](/manual/dwb/editingdata/contact)
    • Wenn als Basisadresse in hugo.toml etwas angegeben wurde, e.g. baseURL = "http://www.diversityworkbench.de/manual/dwb/" dann muss diese auch für Verweise innerhalb der Files verwendet werden.
      • e.g. Bildverweise ![](/manual/dwb/img/IcoFeedback.gif?classes=inline)
      • Dateiverweise [Anmelden](/manual/dwb/database)
      • HUGO relearn erzeugt für Überschriften Anker die man ansteuern kann, e.g. kann man ### Table **AgentResource** über die Adresse /manual/dwb/database/database/#table-agentresource erreichen. Ein Index Eintrag dafür wäre e.g. [AgentResource](/manual/dwb/database/database/#table-agentresource). ACHTUNG - Case sensitiv: ### Table **AgentResource** wird in #table-agentresource übersetzt
    • Kommentare starten mit # ohne folgendes Leerzeichen

Frontmatter

You can change the frontmatter to a default using the documentation tool

  • Steht am Anfang der Datei und ist bei yaml durch --- oben und unten abgegrenzt, e.g. 
    ---
title: Login administration
linktitle: Logins
weight: 5
menuPre: <img src="/manual/dwb/img/Documentation.svg" height="20">&nbsp;
alwaysopen: false
---
  • Seiten die noch in Entwicklung sind kann man mit draft: true im Frontmatter markieren. Diese werden dann nicht in die Ausgabe übernommen
  • Der Titel wird mit title: Login administration angegeben. Dieser erscheint dann auch in der Seite als Überschrift
  • Der Text im Menü kann abweichend definiert werden mit linktitle: Logins. Ansonsten erscheit der Titel im Menü
  • Die Reihenfolge im Menü kann mit weight: 5 angegeben werden. Ansonsten wird alphabetisch sortiert
  • Ein Logo kann man mit menuPre: <img src="/manual/dwb/img/LinkedServer.svg" height="20">&nbsp; hinzufügen. Das Bild sollte *.svg sein
  • Wenn das Untermenue erst beim Anwählen geöffnet werden soll: alwaysopen: false

Bilder

You can adapt the images to a default using the documentation tool

  • Icons die e.g. in den Text integriert werden sollen, müssen folgedermassen eingebaut werden:
    • ![](/manual/dwb/img/Database.svg?height=20px&lightbox=false&classes=inline)
  • Die Bilder am Anfang der Seite werde wie folgt eingebaut:
    • ![](/manual/dwb/img/LinkedServer.svg?height=10vw&lightbox=false)

mit px wird das Bild mitgezoomt, bei vw bleibt es gleich gross

  • noch nicht zu svg konvertierte Bilder die im Fliesstest erscheinen sollen werden wie folgt eingebunden:
    • ![](/manual/dwb/diversitycollection/IcoDelete.gif?classes=inline&lightbox=false)
  • sonstige Bilder mit
    • ![](/manual/dwb/diversitycollection/IcoDelete.gif)

mit der Angabe ...lightbox=false wird verhindert, dass ein Bild beim Anklicken mit der Maus geöffnet wird. Dies sollte bei Bildern die nicht nach svg konvertiert wurden und nicht im Fliesstext erscheinen nicht verwendet werden, damit der User bei kleinen Bildern diese in Originalauflösung betrachten kann. Unten 2 Beispiele

![](/manual/dwb/diversitycollection/IcoDelete.gif?classes=inline&lightbox=false)

![](/manual/dwb/diversitycollection/IcoDelete.gif?classes=inline)

Für Links innerhalb des Manuals kann man shortcodes verwenden. Dafür entweder auf den Namen der Datei oder auf Links von Überschriften (ab ##) verwenden. Diese müssen innerhalb des Manuals eindeutig sein. Für Header als erstes Zeichen # dann Überschrift und alles lower case und Leerzeichen werden durch - ersetzt. Beispiel:

## Main form of diversityexsiccatae

wird zu sofern es sich in der gleichen Datei befindet: {{ % relref "#main-form-of-diversityexsiccatae" % }}

Für Links ausserhalb der Datei werden Verweise unter Einschluss des Dateinamens verwendet:

Verweis auf ein Kapitel innerhalb einer Datei {{ < relref "diversityexsiccatae#main-form-of-diversityexsiccatae" > }}

bzw. nur auf die Datei {{ < relref "diversityexsiccatae" > }}

Leerzeichen zwischen {{ % und % }} entfernen

Von ausserhalb kann e.g. eine Überschrift mit https://www.diversityworkbench.de/manual/dwb/modules/diversityexsiccatae/index.html#main-form-of-diversityexsiccatae aufgerufen werden. Diese können direkt aus dem Manual kopiert werden.

  • hierfür das Logo in den Ordner static kopieren
  • im Ordner layouts einen Ordner partials anlegen
  • dort eine Datei logo.html anlegen
    • in dieser auf das Logo verweisen e.g.: 
      <h4><b>DiversityAgents</b></h4>
<img src="/DA_4D.svg">

Menu- Fusseintrag

  • in static - layouts - partials die Datei menu-footer.html anlegen und anpassen

favicon

Im Ordner static den Ordner images anlegen Datei favicon.ico in der Ordner static/images kopieren

Einschliessen von Dateien

Das Verzeichnis templates enthält Dateien die in andere Dateien über eine shortcode eingeschlossen werden können, e.g.:  {{% include file="templates/template_workbench.md" %}} Diese Dateien dürfen kein frontmatter enthalten. Shortcodes müssen überprüft werden, da diese in der Regel nicht ausgewertet werden.

ER-Diagramm

dieses kann als Mermaid eingebaut werden, e.g.

---
title: ER-Diagram
---
graph LR;
    A[Agent] --> B[AgentContact<br/>Kontaktdaten der Agents]
    A --> C[AgentReference]
    A --> D[AgentIdentifier]
    A --> E[AgentResource]
    A --> F[AgentExternalID]
    G[AgentExternalDatabase] --> F[AgentExternalID]

soll das Diagramm zoombar sein wird die Version 5.23 des Themes benoetigt. Ausserdem kann der Parameter nur für die Shortcode Version angegeben werden, nicht für die Codefences:

{{ < mermaid align="center" zoom="true" > }}
... 
(remove space between {{ and < resp > and }} in header and footer for correct code)
...
{{ < /mermaid > }}

Anpassung des Themes

  • es werden 2 eigene Themes bereitgestellt

    • im Verzeichnes
      • themes
        • relearn
          • static
            • css:
            • theme-dwb-dark.css
            • theme-dwb.css

    diese an DWB Anforderungen anpassen

    • in \themes\relearn\static\css\theme.css 
      #body img.inline {
    display: inline !important;
    margin: 0 !important;
    vertical-align: middle;
    /* vertical-align: bottom; */
}
    • in \themes\relearn\static\css\theme-dwb.css 
      /*--MENU-HEADER-BG-color: rgba( 28, 144, 243, 1 );*/ /* Background color of menu header */
--MENU-HEADER-BG-color: rgba( 220, 220, 220, 1 ); /* Background color of menu header */
--MENU-HEADER-BORDER-color: rgba( 51, 161, 255, 1 ); /*Color of menu header border */

--MENU-SEARCH-color: rgba( 255, 255, 255, 1 ); /* Color of search field text */
/*--MENU-SEARCH-BG-color: rgba( 22, 122, 208, 1 );*/ /* Search field background color (by default borders + icons) */
--MENU-SEARCH-BG-color: rgba( 90, 90, 90, 1 ); /* Search field background color (by default borders + icons) */
/*--MENU-SEARCH-BORDER-color: rgba( 51, 161, 255, 1 );*/ /* Override search field border color */
--MENU-SEARCH-BORDER-color: rgba( 0, 0, 0, 1 ); /* Override search field border color */

Konfiguration - in hugo.toml:

```native
baseURL = "http://www.diversityworkbench.de/manual/dwb/"
languageCode = "en-us"
title = "DiversityAgents"
theme = "relearn"

[outputs]
    home = ["HTML", "RSS", "SEARCH", "SEARCHPAGE"]
    section = ["HTML", "RSS", "PRINT"]
    page = ["HTML", "RSS", "PRINT"]

[params]
    themeVariant = [ "auto", "dwb", "dwb-dark" ]
```

Start des Testservers:

  • mit einem Terminal in das Verzeichnis des Projekts wechseln
  • dort hugo server eingeben.
    • bei Problem mit Sonderzeichen: den Inhalt der Datei config.toml in hugo.toml kopieren und config.toml löschen (beide sollten wenn vorhanden UTF8 sein - werden manchmal als UTF16 angelegt - dieses dann nach UTF8 ändern)
      • Error: “…\diversityworkbench\hugo.toml:1:1”: unmarshal failed: toml: invalid character at start of key: ÿ
  • Im Browser an die angegebene Adresse navigieren, e.g. localhost:1313
  • Wenn als Basisadresse in hugo.toml etwas angegeben wurde, e.g. baseURL = "http://www.diversityworkbench.de/manual/dwb/" dann muss die passende Adresse eingeben werden also e.g. localhost:1313/manual/dwb/