MyCoRe Dokumentation: Tipps und Tricks

An dieser Stelle sollen Lösungen für technische Fragen und Hilfestellungen für den Einstieg in Hugo gegeben werden.

Hugo Shortcodes

Über Shortcodes lassen sich in Hugo Templates für komplexere Abschnitte definieren, die nicht einfach mit HTML oder Markdown darstellbar sind. Oder sie stellen sicher, das für einen bestimmten Aspekt immer dieselbe Darstellung gewählt wird.

{{<hightlight>}} für Codebeispiele

Für die Darstellung von Code-Beispielen wird der von Hugo bereitgestellte Shortcode {{<hightlight>}} verwendet. Die Konfiguration ist in der Hugo-Dokumentation beschrieben. Der erste Parameter enthält die Sprache (z.B. Java, XML, ...) für die die Code-Formatierung vorgenommen werden soll. Zeilennummen können durch die Parameter linenos=table und linenostart eingeblendet werden. Mit dem Parameter hl_lines lassen sich einzelne Zeilen hervorheben.

Anwendungsbeispiel

{{< highlight xml "linenos=table, linenostart=11, hl_lines=1 6" >}}
  <category ID="article">
    <label xml:lang="de" text="Artikel / Aufsatz"/>
    <label xml:lang="en" text="Article / Chapter"/>
    <label xml:lang="it" text="Articolo / Saggio"/>
    <label xml:lang="x-mapping" text="marcgt:article diniPublType:article"/>
  </category>
{{< /highlight >}}                      
11
12
13
14
15
16
<category ID="article">
  <label xml:lang="de" text="Artikel / Aufsatz"/>
  <label xml:lang="en" text="Article / Chapter"/>
  <label xml:lang="it" text="Articolo / Saggio"/>
  <label xml:lang="x-mapping" text="marcgt:article diniPublType:article"/>
</category>				

{{<ref>}} für Links auf interne Seiten

Mit dem Hugo-Shortcode ref können Links auf andere Seiten des Webauftritts verlinkt werden. Es reicht, den Dateinamen der Seite anzugeben. Wenn dieser eindeutig ist, dann ermittelt Hugo automatisch den Pfad. Wenn die Seite nicht (mehr) existiert, bricht Hugo den Buildprozess mit einer Fehlermeldung ab. Dadurch werden tote Links vermieden.

Anwendungsbeispiel

  <span>Hier geht es zum <a href="{{< ref /blog >}}">Blog</a>.</span>

Hier geht es zum Blog.

{{<relURL>}} für relative URLs

Dieser Shortcode erlaubt Zugriff auf die Hugo Funktion relURL, um relative Links in die Webseite einbetten zu können. Das ist dann relevant, wenn die Webseite nicht als Root sondern unter einer URL mit Subpfad betrieben wird.

Anwendungsbeispiel

Relative Adresse dieser Seite: 
<strong>{{<relURL "documentation/developer/dev_docs/dev_docs_howtos/" >}}</strong>

Relative Adresse dieser Seite: /documentation/developer/dev_docs/dev_docs_howtos/

{{<mcr-version>}} für MyCoRe-LTS-Angaben

Dieser Shortcode sollte verwendet werden, wenn im Fließtext auf MyCoRe-LTS-Tags referenziert wird. Mehre Versionsstände können mit Komma (,) getrennt werden.

Anwendungsbeispiel

Das Feature <strong>XY</strong> wurde mit MyCoRe {{<mcr-version "2015.06" >}} eingeführt
und in MyCoRe {{< mcr-version "2016.06,2017.06" >}} verwendet.

Das Feature XY wurde mit MyCoRe 2015.06 eingeführt und in MyCoRe 2016.06 2017.06 verwendet.

{{<mcr-figure>}} für Bilder und Grafiken

Dieser Shortcode sollte zum einheitlichen Einbetten von Bilder und Grafiken verwendet werden. Theoretisch kann die Grafik auch als HTML-Code bzw. SVG-XML bestehen. In Kombination mit dem {{<hightlight>}}-Shortcode können auch Codebeispiele mit Bildunterschriften versehen werden.

Folgende Parameter können verwendet werden:

src URL der Bilddatei / Grafik
classCSS-Klasse
altalternativer Text, wenn das Bild nicht geladen werden kann
widthBreite
heightHöhe
labelFußzeile: Typ der Darstellung
captionBildbeschreibung
attrAngaben zum Urheber

Anwendungsbeispiele

{{< mcr-figure src="http://localhost:1313/images/site/download/mycore_logo_powered_175x55_weiss.jpg" 
         class="border border-primary text-center" 
         label="Logo" caption="powered by MyCoRe" attr="Die MyCoRe-Community" />}}

Logo: powered by MyCoRe

{{< mcr-figure class="border border-secondary" label="SVG-Grafik" 
                 caption="&quot;Kugel in orange&quot;" attr="Die MyCoRe-Community" >}}
    <div class="text-center">
       <svg height="50" width="50">
          <circle cx="25" cy="25" r="20" stroke="black" stroke-width="2" fill="orange" >
      </svg> 
    </div>
{{< /mcr-figure >}}

SVG-Grafik: "Kugel in orange"

{{< mcr-figure label="Konfiguration" caption="<code>mycore.properties</code>">}}
  {{< highlight text "linenos=table" >}}
    # setzt die Standardimplementierung, welche dadurch in der API-URL weggelassen werden kann
    MCR.IIIFImage.Default=Iview 
  {{< /highlight >}}   
{{< /mcr-figure >}}
1
2
# setzt die Standardimplementierung, welche dadurch in der API-URL weggelassen werden kann
MCR.IIIFImage.Default=Iview 

Konfiguration: mycore.properties

{{<mcr-table>}} für Markdown-Tabellen

Dieser Shortcode kann verwendet werden, um Markdown-generierte Tabellen mit class und style Attributen anzureichern. Damit lässt sich u.a. das Tabellen-Layout von Bootstrap nachnutzen.

Folgende Parameter können verwendet werden:

idid Attribut
classCSS Klasse
styleCSS Style Attribut
col-stylesStyle-Attribute (mit | getrennt),
die im <colgroup>-Header der Tabelle gesetzt werden.

Anwendungsbeispiel

{{<mcr-table id="tab_fruits" class="table table-sm table-bordered" style="width:50%"
             col-styles="width:70%;background-color:lightblue;|width:30%" >}}
    | Fruit        | Color  |
    |--------------|--------|
    |Apple         | red    | 
    |Banana        | yellow |
{{</mcr-table>}}         
Fruit Color
Apple red
Banana yellow

{{<mcr-comment>}} für Kommentare in der Dokumentation

Dieser Shortcode kann für Kommentare im Quellcode der Dokumentation verwendet werden. Der Inhalt wird beim Rendern der HTML-Seite ignoriert. So lassen sich beispielsweise einzelne Dokumentationsabschnitte vorübergehend aus der HTML-Seite ausblenden, oder Anmerkungen hinzufügen.

Anwendungsbeispiel

{{<mcr-comment >}}
  RS: Das ist ein interner Kommentar.
{{</mcr-comment >}}

Tipps und Tricks

Hugo

MarkDown

"Im Notfall: HTML"
  • Wenn man nicht mehr weiter weiß, oder die Mächtigkeit von Markdown nicht ausreicht (z.B. bei Tabellen), lässt sich HTML direkt in den Markdown-Code einbetten.
  • Wechsel zwischen Markdown und HTML sollten jedoch auf ein Minimum beschränkt werden.
Markdown CheatSheet
  • Den Einstieg in Markdown kann das Cheatsheet (dt. Spickzettel) Markdown von packetlife.net erleichtern.
Zeilenumbrüche
  • Einfache Zeilenumbrüche können durch einbetten von HTML (<br />) oder durch Einfügen von zwei Leerzeichen (␣␣) am Zeilenende erstellt werden.
  • Eine Leerzeile zwischen den Textblöcken erzeugt einen neuen Absatz.