Die Ansel-Website wird mit Hugo 0.146  erstellt. Dies ist ein statischer Website-Generator, der es ermöglicht, sehr schnell Websites aus Markdown-Dateien zu erstellen. Eine benutzerdefinierte Vorlage und viele benutzerdefinierte Shortcodes wurden für Ansel entwickelt. Sie müssen zuerst die erweiterte Hugo-Version installieren  auf Ihrem Computer, obwohl kleinere Änderungen direkt an den Markdown-Dateien vorgenommen werden können, ohne die gesamte Website neu zu erstellen.

Quellcode herunterladen

This website

1$ git clone https://github.com/aurelienpierreeng/ansel-website
2# Zum Beispiel gespeichert in /home/user/dev/ansel-website
3$ cd ansel-website
4$ sh build-modules.sh

Ansel doc

Ansel Doc ist ein wichtiger Bestandteil der Ansel-Website, aber da es unter einer anderen Lizenz steht und von GNU/GPL dtdocs abgeleitet ist, kann es nicht in diesem Repository sein. Wir möchten beide als Paket bearbeiten, müssen sie jedoch in verschiedenen Repositories separat festhalten können. Hier ist die Lösung.

Ansel Doc wird automatisch als Modul dieser Website auf Ihrer Festplatte als Teil des oben genannten Skripts build-modules.sh abgerufen, das auch die Übersetzungsseiten durch .po-Dateien automatisch generiert. Sie finden es im lokalen Ordner der Website unter _vendor/github.com/aurelienpierreeng/ansel-doc/. Keine Datei sollte dort manuell bearbeitet werden, dies ist nur für automatisch generierte Inhalte.

Um Ansel-Dokumente zu bearbeiten, tun Sie folgendes:

1$ git clone https://github.com/aurelienpierreeng/ansel-doc
2# Stored for example in /home/user/dev/ansel-doc
3$ cd ansel-doc

Und dann den (englischen) Inhalt von ansel-doc/content bearbeiten.

Interaktive Bearbeitung/Live-Vorschau

Start the development server

Hugo lässt Sie eine gerenderte Version der Website auf einem lokalen Entwicklungsserver öffnen, um Ihre Änderungen in Ihrem Webbrowser vorzuschauen.

Wenn Sie nur diese Website bearbeiten möchten, führen Sie aus dem Verzeichnis ./ansel-website:

1hugo server --disableFastRender

Wenn Sie die Dokumente bearbeiten und die Ergebnisse in Echtzeit als Teil dieser Website sehen möchten, nachdem Sie die Dokumente geklont haben (siehe vorherigen Schritt), führen Sie aus dem Verzeichnis ./ansel-website:

1env HUGO_MODULE_REPLACEMENTS="github.com/aurelienpierreeng/ansel-doc -> ../../ansel-doc/" hugo server --disableFastRender

Dieser Trick lädt das Doc-Modul dynamisch von Ihrem lokalen Ordner anstelle von Github, was bedeutet, dass die lokal vorgenommenen Änderungen an den Docs sofort in der Hauptwebsite über Ihren Entwicklungsserver erscheinen.

Updating websites translations

Siehe Übersetzung.

Dateien bearbeiten

Obsidian öffnen

Öffnen Sie ./ansel-website/content als Obsidian-Vault. Obsidian kann Ordner-Symlinks wie lokale Ordner auflösen, sodass wir im Grunde die ganze Website sehen, was das Erstellen von internen Links zwischen Doc und Website im Editor erleichtert.

Die Arbeit in Obsidian ist deutlich angenehmer als in VS Code, um „Text“ Text zu bearbeiten (im Gegensatz zu Code-Text in Monospace), da der Editor weniger aufgebläht ist und Monospace-Schriftarten nach ein paar Stunden bei vollen Absätzen augenbelastend sind.

  • Hugo Markdown unterstützt keine Obsidian-Callouts . Sie müssen die oben gezeigten Warnkästchen als Hugo-Shortcodes verwenden, aber sie werden in Obsidian nicht gerendert,
  • Hugo unterstützt keine Obsidian-Wikilinks , sodass Sie zu den üblichen Markdown-Links mit relativen Pfaden übergehen müssen. Dennoch bietet Obsidian für diese eine Pfad-Vervollständigung an.
  • Obsidian unterstützt keine Markdown-Definitionslisten , Sie können sie jedoch dennoch verwenden (sie werden in Vorschauen einfach nicht gerendert),
  • Obsidian unterstützt keine Markdown-Überschriften-IDs ,

Jedoch:

  • Obsidian unterstützt Hugo-Tags in YAML-Frontmatter und implementiert sie in einer viel ansprechenderen Weise, die einer horizontalen Inhaltsverknüpfung viel mehr Sinn verleiht,
  • Obsidian unterstützt Hugo Aliase  für Seitenumleitungen,

Verbesserung der Inhaltsverknüpfung

Horizontales Verlinken, durch Tags und interne Links, ist genauso wichtig wie das vertikale Verlinken, nach hierarchischen Bäumen.

Obsidian kann die Vault-weise verfügbaren Tags zur Wiederverwendung anzeigen:

image

Es kann auch die besten Kandidaten für interne Links für jedes Schlüsselwort auf der Seite unter den zusammenklappbaren “Unverlinkten Erwähnungen” anzeigen:

image

Checking content organization

Es ist oft schwierig, das Kettmachen von Überschriften in einer Markdown-Seite zu folgen, wenn man einen typischen Code-Editor verwendet. Obsidian hat ein “Gliederungs”-Widget, das es erlaubt, die Inhaltsübersicht im Blick zu behalten, während man schreibt, um sicherzustellen, dass die Hierarchie der Überschriften konsistent bleibt:

image

Richtlinien

Die Dokumentation ist kein Handbuch oder Kurs. Sie sollte die Fragen beantworten:

  • “Was macht das GUI?”
  • “Wie kann ich die Software konfigurieren?”
  • “Was sind die Engpässe, Fallstricke, Einschränkungen und Fallen?”.

Die Dokumentation erwartet, dass der Leser was zu tun ist und erklärt wie es zu tun. Start-to-End-Workflows, Tutorials, wissenschaftlicher Hintergrund usw., also das Was und Warum sind auf der Website ( Ressourcen, Workflows).

Content folder

Der Inhaltsordner befindet sich im Verzeichnis content/ und die Struktur von Ordnern und Unterordnern wird die Struktur von Sektionen und Untersektionen auf der Website erzeugen. Dateien werden in Markdown geschrieben und enden mit der Erweiterung .md. Jede Datei sollte den folgenden Header (Frontmatter) haben:

 1---
 2title: Seitentitel
 3date: 2022-12-04T02:19:02+01:00
 4lastmod: 2022-12-31
 5draft: false
 6weight: 120
 7tags:
 8    - Farbwissenschaft
 9    - Pipeline
10---
  • Der Titel ist obligatorisch. Bitte verwenden Sie Anfangsbuchstaben, wie in der echten Sprache.
  • Das Datum wird einmal bei der Erstellung der Seite festgelegt und sollte danach nie geändert werden.
  • Aktualisieren Sie das lastmod-Datum mit dem heutigen Datum jedes Mal, wenn Sie eine Datei aktualisieren, und fügen Sie es hinzu, falls nicht vorhanden. Im Internet ist jeder Inhalts-Chang- und dies hilft den Lesern zu erraten, ob die Seite zum Zeitpunkt des Lesens noch relevant ist.
  • draft auf true gesetzt bedeutet, dass die Seite im Repository (im Quellcode) sein wird, aber nicht auf der Website-Frontend erscheint. Auf false gesetzt ist die Seite auf dem Frontend sichtbar.
  • tags sind optional, aber willkommen. Der Inhalt ist standardmäßig vertikal (hierarchisch) organisiert. Tags helfen dabei, horizontale (thematische) Links zwischen Seiten zu erstellen. Relevante Tags könnten “Filmverarbeitung”, “HDR”, “Monochrom” usw. sein. Wiederverwenden bestehender Tags hat Priorität. Tags sollten immer eine Liste sein, auch wenn es nur eines gibt (sonst bricht der Hugo-Build).

Seitenanker

Wenn Sie Links zu Seitenankern erstellen, wie /my-post.md#some-heading, stellen Sie sicher, dass zwischen dem Seiten-Slug und dem Hashtag # kein Schrägstrich / in Ihrem Markdown-Code eingefügt wird, oder sonst wird die Datei als ein Verzeichnis genommen und nicht gefunden.

Header (Überschriften)

H1-Überschriften (codiert # Titel in Markdown) sind für Seitentitel reserviert und jede Seite sollte genau ein H1 haben. Darktable-doc hat sich hier schwer vertan, indem sie H1 als Abschnittstitel verwendet haben, dies ist sowohl ein SEO- als auch ein Barrierefreiheitsfehler. Das Web ist semantisch, weil es sowohl für Crawler als auch für Screenreader genauso entworfen wurde wie für Menschen.

Beachten Sie, dass Hugo automatisch Ankerlinks für Überschriften generiert, basierend auf dem Text der Überschrift. Verzichten Sie daher auf die Verwendung von Symbolen in Überschriften, insbesondere (Back-)Slashes, die die Ankerlinks durcheinander bringen.

Also be aware that these headings anchors may be used in other pages to make direct links. Changing the text of an heading will break its anchor and may break external links. To avoid breaking anchors in external links, you can change the heading text but force their ID to the previous, like so:

1### Meine neue Überschrift {#mein-alter-anker}

Dies bewahrt externe Links auf /mein-post/#mein-alter-anker. Siehe die Details… 

Einbetten von Bildern

Hugo behandelt Bilder als Seiten-Assets. Es gibt globale Assets, für Bilder, die auf mehreren Seiten wiederverwendet werden, die in einem assets/ Unterordner im Hauptquellcodeordner gespeichert sind, und lokale Assets, die im selben Ordner wie die Seite, die sie verwendet, gespeichert sind.

Wie bei internen Links muss alles relativ zum Quellcode als auf dem lokalen Dateisystem gehostet verlinkt werden, nicht relativ zum kompilierten HTML.

Siehe wie man Bilder übersetzt.

Screenshots

Screenshots sind die Grundlagen jeder Front-End-Softwaredokumentation. Die Darktable-doc-Bearbeiter lehnen sie ab, weil sie nicht übersetzt werden können und aufgrund der Häufigkeit von GUI-Änderungen bald veraltet sein werden, aber das ist ein großer pädagogischer Fehler. Selbst in der falschen Sprache helfen Screenshots, zu sehen, wonach man im Fenster suchen sollte. Verwenden Sie sie. Sie werden veraltet und möglicherweise nicht übersetzt, genauso wie der Rest des Textes.

Info, Warnungen, Alarme

Das Ansel-Thema von der Hauptwebsite bietet Shortcodes, um Warnungen und Informationskästen mithilfe des Hugo-Templating-Systems zu erstellen. Hier ist der Code:

1{{< warning >}}
2Dies ist der Ort, an dem Sie den Benutzern mitteilen, was sie wissen sollten, da das, was allgemein eine gute Idee erscheinen mag, in bestimmten Umständen wirklich schlecht sein kann.
3{{< /warning >}}
1{{< note >}}
2Ihre Randnotiz hier.
3{{< /note >}}
1{{< advice >}}
2Ihr freundlicher Ratschlag hier.
3{{< /advice >}}
1{{< danger >}}
2Hier erinnern Sie die Benutzer daran, dass sie frei sind, Blödsinn zu machen, aber es wird Konsequenzen geben.
3{{< /danger >}}

Der Inhalt der Kästen kann auch Markdown verwenden.

Vorher/Nachher-Schieberegler

Erneut können Sie mithilfe des Hugo-Templating-Systems Vorher/Nachher-Schieberegler anzeigen, bei denen beide Bilder überlagert sind. Dies ähnelt der Snapshot-Funktion von Ansel & Darktable-Dunkelkammer und kann effizient den Effekt von Modulen und Einstellungen erklären, in einer Weise, dass Benutzer sie in der GUI reproduzieren können. Sowohl das Vorher- als auch Nachher-Bild müssen dieselbe Größe in Pixel haben.

1{{< compare after="./img-after.jpg" before="./img-before.jpg" >}}
2Ihre Schiebereglertitel gehen hier hin.
3{{< /compare >}}

Mathematik

Die Dokumentation unterstützt MathJax, konfiguriert für LaTeX-Syntaxunterstützung. Obwohl das Ziel nicht darin besteht, wissenschaftliche Literatur zu schreiben, gibt es einige Algorithmen, die besser als Gleichungen gezeigt werden, anstatt Textblöcke zu schreiben.

Inline-LaTeX sollte in $ eingeschlossen werden, Blockgleichungen in $$. Wenn Sie LaTeX verwenden, müssen Sie Hugo benachrichtigen, das Mathjax-Skript auf der Seite anzuhängen, indem Sie latex: true im Header/Frontmatter der Markdown-Seite einstellen.

Mermaid-Diagramme

Ansel macht einen schweren Einsatz von Pipelines, und diese werden am besten mit Flussdiagrammen beschrieben. Mermaid.js wird jetzt nativ auf Github und in Visual Studio Code unterstützt und ist großartig für diesen Zweck. Sie können es hier visuell ausprobieren  und den Code der Diagramme innerhalb von Markdown-Codeblöcken wie folgt kopieren und einfügen:

1    ```mermaid
2    graph TD
3        A[Weihnachten] -->|Geld bekommen| B(Einkaufen gehen)
4        B --> C{Lass mich nachdenken}
5        C -->|Eins| D[Laptop]
6        C -->|Zwei| E[iPhone]
7        C -->|Drei| F[fa:fa-car Auto]
8    ```

This renders:

graph TD
    A[Weihnachten] -->|Geld bekommen| B(Einkaufen gehen)
    B --> C{Lass mich nachdenken}
    C -->|Eins| D[Laptop]
    C -->|Zwei| E[iPhone]
    C -->|Drei| F[fa:fa-car Auto]

Symbole aus Font Awesome v5  werden von der Ansel-Hauptwebsite und Dokumentation unterstützt, mithilfe der Syntax fa:fa-IHR-SYMBOL-CODE, wie im obigen Beispiel gezeigt. Verwenden Sie die Font Awesome v5-Suchmaschine , um den fa- Code der von Ihnen verwendeten Symbole zu erhalten.

Mermaid graphs are rendered client-side in SVG at display size and can be translated as text. Hugo is configured to detect these graphs automatically and load the javascript library only when needed. Github can also render Mermaid graphs natively, when displaying Markdown files.

Ändern von Seiten-URLs

Manchmal ergibt es Sinn, den Inhalt neu zu organisieren und die Pfade einiger Seiten zu ändern. Um keine externen Links zu brechen, müssen Sie die alte URL der neuen Seite als Alias im Frontmatter der neuen Seite wie folgt aufzeichnen:

1aliases:
2    - /meine-alte-url/
3    - /eine-andere-noch-ältere-url

Notizen

RSS-Feed

Die Dokumentation hat einen lokalisierten RSS-Feed, bisher:

Dies ist ungewöhnlich und soll den Benutzern helfen, Änderungen und Entwicklungen nachzuverfolgen, indem sie den RSS-Feed abonnieren oder ihn mit Bots verbinden.

Das Datum der Dokumentationsseiten, das im RSS-Feed gesetzt wird, ist der Parameter lastmod, also die Zeit der letzten Änderung. Da RSS kein zuletzt geändertes Datum hat, ist das bisher das beste, was ich gefunden habe.

Translated from English by : ChatGPT. In case of conflict, inconsistency or error, the English version shall prevail.