Markdown-Syntax

Sobald das Git-Repo dieses Blogs online ist, wird jeder in der Lage sein, Inhalte zu ändern oder Fehler zu korrigieren. Ob und in welchen Fällen ich Pull Requests annehme, das werde ich in Zukunft noch beschreiben.

FIXME, noch weitere Dinge erklären.

Einen neuen Blogbeitrag erstellen

Mindestanforderungen für einen Blogbeitrag

Ein Blogbeitrag sollte mindestens enthalten:

• Angaben im Front Matter (siehe hier).
  • Einen aussagekräftigen Titel.
  • Passende Tags (an den vorhandenen Tags orientieren und nur wenig neue Tags erstellen). Tags immer in der Mehrzahl verwenden, außer bei feststehenden Begriffen.
  • Bereits verwendete Tags kann man mit dem Hugo Helper (-ft xyz) suchen und deren Anzahl anzeigen lassen.
  • Eine Beschreibung mit maximal ~200 Zeichen (siehe hier).
• Seitenbild (siehe hier).

Front Matter

Als Vorlage kann man dieses Front Matter benutzen:

title: Fotos vom Ausflug 12.04.2022
---
slug: fotos-ausflug
date: 2022-04-13T00:55:46+02:00
draft: false
author: Name
categories:
  - Allgemein
tags:
  - Fotos
  - Natur
  - Kagube
  - Pforzheim
---

Titel (Title)

Der Titel einer Seite.

Slug

URL des Blogbeitrags. Mit dem Datum wird im oberen Beispiel dann die URL natenom.de/2022/04/fotos-ausflug.

comments

Wird dieser Parameter auf false (Standardwert ist true) gesetzt, dann wird die Info zu Anmerkungen/Kommentaren nicht angezeigt.

jsoncomments

Wird dieser Parameter auf true (Standardwert ist false) gesetzt, dann wird die Datei comments.json im Kommentarbereich eines Blogbeitrags eingebunden. Die Syntax der json-Datei ist hier dokumentiert.

Die Datei comments.json kann mit Hilfe des Hugo Helpers erstellt werden.

Beschreibung

Man kann im Front Matter eine Beschreibung einfügen:

description: Beschreibung

Alternativ verwende man dieses Tag:

<!--more-->

Dadurch wird alles vom Anfang des Beitrags bis zu dieser Zeile als Beschreibung verwendet.

Empfohlener Blogbeitrag

Damit ein Blogbeitrag rechts in der Sidebar in das Widget “Empfohlene Beiträge” eingefügt wird, fügt man im Front Matter ein:

featured: true

Angepinnt

Einen Beitrag kann man auf der Startseite im Blog anpinnen mit dem Eintrag im Front Matter:

pinned: true

URL

Sollte, wie meist bei Pages, also Einzelseiten wie dieser hier, eine bestimmte URL für die Seite benötigt werden, so kann man das Tag url verwenden, z. B. für die Seite hier:

url: /ueber/markdownsyntax/

Beitragsbilder

Dateien, die bestimmte Teilstrings enthalten und im Hauptverzeichnis eines Page Bundles liegen, werden automatisch genutzt für:

• cover und thumbnail: Wird nur in der Liste von Blogbeiträgen als Thumbnail angezeigt.
• feature: Wird nur im geöffneten Blogbeitrag oben im Header angezeigt.

Gibt es eines der drei, wird diese automatisch als Bild für Twitter Cards und Open Graph verwendet.

Grundsätzliches

Code

Man kann Code auf verschiedene Weisen darstellen:

• Codefence mit Angabe der Sprache, als mit 3 Backticks (Details zum Syntax-Highlighting)
• Hightlight Shortcode builtin (Details in offizieller Doku)
• Einrückungen

Dinge, die im Blog und Wiki gleichermaßen gelten

Weil diese Dinge für Blog und Wiki gelten, sind sie nur hier beschrieben und im Wiki wird hierher verlinkt.

Interwiki-Links

Trotz des Namens sind solche Interwiki-Links sowohl im Blog als auch im Wiki nutzbar.

Folgende Interwiki-Links stehen zur Verfügung:¹

Die Syntax für die Nutzung ist an die von Markdown angelehnt:

[Link zu meinem Wiki](nat-wiki>docs/fahrrad/faq/strasse_trotz_radweg/)

Das wird aufgelöst zu:

[Link zu meinem Wiki](https://wiki.natenom.de/docs/fahrrad/faq/strasse_trotz_radweg/)

Seite(n) verschieben

Verschiebt man (nur aus guten Gründen) eine Seite innerhalb des Wikis oder Blogs (z. B. innerhalb von pages/), dann muss im Front Matter der Parameter aliases: hinzugefügt werden mit dem alten Standort der Seite.

Beispielsweise hatte ich mal diese Anweisungen hier verschoben von /docs/ueber/format/ nach /docs/ueber/mitarbeit/. Der richtige Alias-Eintrag war deshalb:

aliases:
  - /docs/ueber/format/

Benennt man eine einzelne Seite nur um, ohne den Standort innerhalb der Verzeichnishierarchie zu verändern, dann reicht es aus, den Namen der alten Datei in Aliases einzutragen. Hieß die alte Seite z. B. ohne_kuehlschrank_leben.md und benennt man diese um in kuehlschrank.md, dann ist der passende Eintrag in Aliases:

aliases:
  - ohne_kuehlschrank_leben

Shortcodes

Bitte nur so wenig wie möglich Shortcodes verwenden und so oft wie möglich die Formatierungen von Markdown verwenden.

Bilder/Fotos/Screenshots

Bilder Screenshots sollten nur verlinkt werden, wenn es notwendig ist, das Bild in groß sehen zu müssen, um es erkennen zu können. Wenn ein Bild nicht breiter als ca. 600 Pixel ist, dann reicht es aus, wenn es eingebettet wird, aber nicht verlinkt.

Den Hugo Helper kann man nutzen, um Bilder im Page Bundle auf maximal 4000x4000 Pixel zu beschränken, Metadaten aus Bildern und Videos zu entfernen, und mehr. Aufruf ist hgh.py -pp.

• Alle Bilder werden auf 4000x4000 verkleinert, es sei denn im Dateinamen ist pano oder sphere enthalten.
• Enthält der Dateiname 2k, wird auf maximal 2000x2000 Pixel verkleinert.
• Zusätzlich werden fast alle Exifdaten entfernt außer diejenigen, die für Fotos relevant sind.
• Bei Spheres (360°-Fotos) bleiben zusätzlich die Metadaten erhalten, die für die Darstellung dieser Spheres notwendig sind.

Einzelbilder per Markdown-Syntax

Die Syntax ist:

![Alt Text](pfad/zu_bild.jpg "Bildbeschreibung unter dem Bild")

Man kann auch ein Bild einbinden und darauf einen Link auf ein anderes Bild oder auf das Orinalbild legen:

[![](bild.jpg)](bild.jpg)

Oder einen Link auf ein Bild legen:

[![](bild.jpg)](/url)

Einzelbild(er) per figure

Den Shortcode figure bitte nur benutzen, wenn:

• Das Bild verlinkt sein soll UND Titel oder Beschreibung (caption) enthält, in der Markdown notwendig ist, was innerhalb von Caption möglich ist, in der Markdown-Syntax (siehe Punkt oben drüber), allerdings nicht.
• Das Bild kleiner dargestellt werden soll als das Original bzw. die maximale Breite im Blog (816 Pixel), obwohl das Originalbild breiter ist.

Einschränkung: Derzeit funktioniert figure nur, wenn das Bild im Pagebundle liegt. Liegt es auf einem Remote-Server, dann geht die Einbindung nur via Markdown-Syntax.

Syntax für figure:

{{< figure src="" link="" alt="" title="" caption="" width="" float="" >}}

Mit dem Attribut float= kann man Float entweder auf left oder right setzen. So ist es möglich, Bilder nebeneinander zu positionieren. Damit danach der Text wieder in einem eigenen Absatz anfängt, kann man diesen Shortcode verwenden:

{{< clear >}}

Galerie

Bitte keine Galerien mehr verwenden, sondern nur noch Einzelbilder mit Figure. Das ist fürs Durchschauen des Blogs später schöner, weil man auch zu jedem Bild etwas schreiben kann. Auch ohne externe Tools.

Ist zwar mehr Arbeit, liefert aber später mehr Anhaltspunkte für Erinnerungen.

Sollen mehrere Bilder mit Overlay angezeigt werden, dann eine Galerie verwenden:

{{< nat_gallery match="images/*" >}}

Audio/Video

Bitte für Audio UND Video den Shortcode video nutzen und dabei nur die notwendigen Attribute angeben:

{{< video src="file.mp4" >}}
{{< video src="42.oga" >}}

Optionale Attribute:

• caption: Untertitel des Videos, das darunter angezeigt wird. Es darf Markdown verwendet werden.
• linktext: Text für den Link zum Video. Nur angeben, wenn es abweichen soll von shortcode_video_linktext in der config.toml.
• type: MIME-Typ der angegebenen Datei. Für Medien innerhalb eines Page Bundles muss man type nicht angeben (da Hugo das selbst herausfindet und angibt) sondern nur bei Dateien, die via http oder https eingebunden werden. Ein angegebenes type hat immer die höchste Priorität.
  • Video z. B. video/mp4
  • Audio z. B. audio/ogg
• preload: none|auto|metadata (Siehe auch hier.)
• poster: Es ist möglich, ein selbst definiertes Vorschaubild für das Video mittels anzugeben. Das funktioniert jedoch nur, wenn preload=none verwendet wird.

Anker manuell definieren

## Local storage {#anker-123}

Verlinken kann man diese dann mit:

[Linktext](/url#anker-123)

Bitte den Namen von manuellen Ankern immer mit a_ beginnen, um sie von automatisch gesetzten Ankern für Überschriften zu trennen.

360°-Foto mit optionaler Karte

Der Shortcode sphere ermöglicht es, 360°-Fotos interaktiv und entzerrt darzustellen. Zusätzlich kann man mit dem selbst erstellten Shortcode eine Karte unter dem Foto anzeigen lassen.

Der Shortcode hat folgende Möglichkeiten:

• src: Link zum 360°-Foto
• (optional) caption: Bildunterschrift
• (optional) osmurl: Wird als Link angezeigt und soll eine Karte von OSM mit einer Markierung enthalten von dem Ort, wo das Foto aufgenommen wurde.
• (optional) osmembedurl: Die Embed-URL (Verweis auf die OSM-Karte), die unter dem 360°-Foto als iframe angezeigt wird.
• (optional) north: In den Metadaten ist der Nullpunkt (Startpunkt) eines Panoramas angegeben. Hier gibt man einen Wert zwischen +-0 bis 360 an, damit es eine Markierung gibt, die den Norden angibt.
• (optional) direction: Ein Wert zwischen +-0deg bis 360deg, 0 wäre Nord. der angibt, in welche Richtung ein Panorama beim Laden zeigt.
• (optional) autorotate: Ein Wert zwischen -360 und 360, der angibt, ob ein Panorama automatisch gedreht wird, in welche Richtung und wie schnell.

Weitere Infos für north, direction und autorotate (eigentlich autorotatePitch) gibt es hier.

Hier der Shortcode für dieses Beispiel:

{{< sphere src="2023-02-24-neuhausen-1-small.webp" caption="Landschaft nördlich von Neuhausen (Enzkreis)" osmurl="https://www.openstreetmap.org/?mlat=48.80035&mlon=8.77323#map=15/48.8010/8.7731" imgsize="8,6" osmembedurl="https://www.openstreetmap.org/export/embed.html?bbox=8.755288124084474%2C48.79391687059584%2C8.79112243652344%2C48.8067645369292&amp;layer=mapnik&amp;marker=48.800341115118435%2C8.773205280303955" >}}