De Ansel-website is gebouwd met Hugo 0.146 . Dit is een generator voor statische websites waarmee je zeer snelle websites kunt bouwen op basis van Markdown-bestanden. Voor Ansel zijn een aangepast sjabloon en veel aangepaste shortcodes gebouwd. Je moet eerst de extended-versie van Hugo installeren  op je computer, hoewel kleine wijzigingen rechtstreeks in de Markdown-bestanden kunnen worden aangebracht zonder de hele website te bouwen.

De broncode ophalen

Deze website

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

Ansel-doc

Ansel Doc is een belangrijk onderdeel van de Ansel-website, maar omdat het onder een andere licentie valt en geforkt is van de GNU/GPL-dtdocs, kan het niet in deze repo staan. We willen beide als een pakket bewerken, maar we moeten ze afzonderlijk kunnen committen naar verschillende repositories. Hier is de oplossing.

Ansel-doc wordt automatisch op je schijf opgehaald als een module van deze website, als onderdeel van het bovenstaande build-modules.sh-script, dat ook de vertaalde pagina’s automatisch genereert via .po-bestanden. Je vindt het in de lokale map van de website, onder _vendor/github.com/aurelienpierreeng/ansel-doc/. Daar mag geen enkel bestand handmatig worden bewerkt; dit is uitsluitend voor automatisch gegenereerde inhoud.

Om de Ansel-docs te bewerken, doe je

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

En bewerk vervolgens de (Engelse) inhoud van ansel-doc/content.

Interactief bewerken/live-voorbeeld

De ontwikkelserver starten

Met Hugo kun je een weergegeven versie van de website openen, op een lokale ontwikkelserver, om je wijzigingen in je webbrowser te bekijken.

Als je alleen deze website wilt bewerken, voer je vanuit de map ./ansel-website uit:

1hugo server --disableFastRender

Als je de docs wilt bewerken en de resultaten in realtime als onderdeel van deze website wilt zien, voer dan, nadat je de docs hebt gekloond (zie de vorige stap), vanuit de map ./ansel-website uit:

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

Deze truc laadt de docs-module dynamisch vanuit je lokale map in plaats van vanaf Github, wat betekent dat de lokale wijzigingen aan de docs onmiddellijk in de hoofdwebsite verschijnen via je ontwikkelserver.

Websitevertalingen bijwerken

Zie Vertalen.

Bestanden bewerken

Obsidian openen

Open ./ansel-website/content als een Obsidian-kluis. Obsidian kan symlinks naar mappen oplossen alsof het lokale mappen zijn, zodat we de website eigenlijk als een geheel zien, wat het makkelijker maakt om in de editor interne links te leggen tussen doc en website.

Werken in Obsidian is aanzienlijk aangenamer dan werken in VS Code om „tekst"-tekst te bewerken (in tegenstelling tot code-tekst in monospace), omdat de editor minder overladen is en monospace-lettertypen na een paar uur vermoeiend zijn voor de ogen bij volledige alinea’s.

  • Hugo-Markdown ondersteunt geen Obsidian-callouts . Je moet de hierboven getoonde waarschuwingsvakken gebruiken als Hugo-shortcodes, maar die worden niet weergegeven in Obsidian,
  • Hugo ondersteunt geen Obsidian-wikilinks , dus je zult moeten vasthouden aan gewone Markdown-links met relatieve paden. Dat gezegd hebbende, Obsidian biedt padauto-aanvulling daarvoor.
  • Obsidian ondersteunt geen Markdown-definitielijsten , maar je kunt ze toch gebruiken (ze worden alleen niet weergegeven in voorbeelden),
  • Obsidian ondersteunt geen Markdown-kop-ID’s ,

Echter:

  • Obsidian ondersteunt Hugo-tags in de Yaml-frontmatter, en implementeert ze op een veel prettigere manier die veel meer betekenis geeft aan horizontaal contentlinken,
  • Obsidian ondersteunt Hugo-aliassen  voor het doorverwijzen van pagina’s,

Het verweven van inhoud verbeteren

Horizontaal linken, via tags en interne links, is net zo belangrijk als verticaal linken, dat hiërarchische bomen volgt.

Obsidian kan de in de hele kluis beschikbare tags tonen voor hergebruik:

image

Het kan ook de beste kandidaat-interne-links voor elk trefwoord op de pagina tonen, onder de uitklapbare sectie „Unlinked mentions":

image

De organisatie van inhoud controleren

Het is vaak lastig om de aaneenschakeling van koppen op een Markdown-pagina te volgen wanneer je een typische code-editor gebruikt. Obsidian heeft een „outline"-widget waarmee je de inhoudsopgave in het zicht kunt houden tijdens het schrijven, om ervoor te zorgen dat de hiërarchie van koppen consistent is:

image

Richtlijnen

De documentatie is geen handleiding of cursus. Ze zou de volgende vragen moeten beantwoorden:

  • „wat doet de GUI?"
  • „hoe kan ik de software configureren?"
  • „wat zijn de knelpunten, kanttekeningen, beperkingen en valkuilen?".

De documentatie verwacht dat de lezer weet wat te doen en zal uitleggen hoe het te doen. Werkwijzen van begin tot eind, tutorials, wetenschappelijke achtergrond enz., oftewel het wat en het waarom, horen op de website (bronnen, werkwijzen).

Content-map

De content-map bevindt zich in de directory content/ en de structuur van mappen en submappen produceert de structuur van secties en subsecties op de website. Bestanden zijn geschreven in Markdown en eindigen op de extensie .md. Elk bestand moet de volgende header (frontmatter) hebben:

 1---
 2title: This page title
 3date: 2022-12-04T02:19:02+01:00
 4lastmod: 2022-12-31
 5draft: false
 6weight: 120
 7tags:
 8    - color science
 9    - pipeline
10---
  • De titel is verplicht. Gebruik hoofdletters aan het begin, zoals in echte taal.
  • De datum wordt eens en voor altijd ingesteld bij het aanmaken van de pagina en mag daarna nooit meer veranderen.
  • Werk de lastmod-datum bij met de datum van vandaag telkens wanneer je een bestand bijwerkt, en voeg deze toe als deze ontbreekt. Op het internet is alle inhoud vergankelijk, en dit helpt lezers in te schatten of de pagina op het moment van lezen nog relevant is of niet.
  • draft ingesteld op true betekent dat de pagina in de repository (in de broncode) staat, maar niet op de front-end van de website verschijnt. Ingesteld op false is de pagina zichtbaar op de front-end.
  • tags zijn optioneel maar welkom. De inhoud is standaard verticaal (hiërarchisch) georganiseerd. Tags helpen om horizontale (thematische) links tussen pagina’s te leggen. Relevante tags zouden „film processing", „HDR", „monochrome" enz. kunnen zijn. Hergebruik bij voorkeur bestaande tags. Tags moeten altijd een lijst zijn, zelfs als er maar één is (anders breekt de Hugo-build).

Pagina-ankers

Als je links maakt naar pagina-ankers, zoals /my-post.md#some-heading, zorg er dan voor dat je geen schuine streep / invoegt tussen de pagina-slug en de hekjes # in je Markdown-code, anders wordt het bestand aangezien voor een directory en niet gevonden.

Titels (koppen)

H1-titels (gecodeerd als # Title in Markdown) zijn gereserveerd voor paginatitels en elke pagina zou precies één H1 moeten hebben. darktable-doc heeft het hier flink verknoeid door H1 als sectietitels te gebruiken; dit is zowel een SEO- als een toegankelijkheidsfout. Het web is semantisch omdat het is ontworpen voor crawlers en schermlezers, net zozeer als voor mensen.

Wees je ervan bewust dat Hugo automatisch ankerlinks voor koppen genereert, met de tekst van de kop. Vermijd daarom het gebruik van symbolen in koppen, vooral (achterwaartse) schuine strepen, die de ankerlinks in de war sturen.

Wees je er ook van bewust dat deze kopankers in andere pagina’s gebruikt kunnen worden om directe links te maken. Het wijzigen van de tekst van een kop breekt het anker ervan en kan externe links breken. Om te voorkomen dat ankers in externe links breken, kun je de koptekst wijzigen maar hun ID forceren naar de vorige, zoals zo:

1### My New Heading {#my-old-heading}

Dit behoudt externe links naar /my-post/#my-old-heading. Zie de details… 

Afbeeldingen insluiten

Hugo behandelt afbeeldingen als pagina-assets. Er zijn globale assets, voor afbeeldingen die op meerdere pagina’s worden hergebruikt, opgeslagen in een submap assets/ van de hoofd-broncodemap, en lokale assets, opgeslagen in dezelfde map als de pagina die ze gebruikt.

Net als bij interne links moet alles relatief ten opzichte van de broncode zoals gehost op het lokale bestandssysteem worden gelinkt, niet relatief ten opzichte van de gecompileerde HTML.

Zie hoe je afbeeldingen vertaalt.

Schermafbeeldingen

Schermafbeeldingen zijn de basis van elke documentatie voor front-end-software. De beheerders van darktable-doc weigeren ze op grond van het feit dat ze niet vertaald kunnen worden en dat ze binnenkort verouderd zullen zijn gezien de frequentie van GUI-wijzigingen, maar dat is een enorme pedagogische fout. Zelfs in de verkeerde taal helpen schermafbeeldingen om te zien waar je in het venster naar moet zoeken. Gebruik ze. Ze zullen verouderd raken en misschien niet vertaald worden, net als de rest van de tekst.

Info, waarschuwingen, alerts

Het Ansel-thema van de hoofdwebsite biedt shortcodes om alerts en infovakken te maken met het templating-systeem van Hugo. Hier is de code:

1{{< warning >}}
2This is where you say what users should be aware of, because what may sound like a good idea in general may be really bad in some circumstances.
3{{< /warning >}}
1{{< note >}}
2Your side note here.
3{{< /note >}}
1{{< advice >}}
2Your friendly advice here.
3{{< /advice >}}
1{{< danger >}}
2This is where you remind users that they are free to do shit but there will be consequences.
3{{< /danger >}}

De inhoud van de vakken kan ook Markdown gebruiken.

Voor/na-schuifregelaars

Wederom kun je, met het templating-systeem van Hugo, voor/na-schuifregelaars weergeven waarbij beide afbeeldingen over elkaar heen liggen. Dit lijkt op de snapshot-functie van de donkere kamer van Ansel & darktable en kan het effect van modules en instellingen efficiënt uitleggen op een manier die gebruikers in de GUI kunnen reproduceren. Zowel de voor- als de na-afbeelding moeten dezelfde grootte in pixels hebben.

1{{< compare after="./img-after.jpg" before="./img-before.jpg" >}}
2Your slider legend goes here.
3{{< /compare >}}

Wiskunde

De docs ondersteunen MathJax, geconfigureerd voor ondersteuning van LaTeX-syntaxis. Hoewel het doel niet is om wetenschappelijke literatuur te schrijven, zijn er sommige algoritmen die uit vermenigvuldigingen en optellingen bestaan en die gemakkelijker als vergelijkingen worden getoond dan als blokken tekst.

Inline-LaTeX moet worden ingesloten in $, blokvergelijkingen ingesloten in $$. Als je LaTeX gebruikt, moet je Hugo laten weten dat het het Mathjax-script aan de pagina moet toevoegen door latex: true in te stellen in de header/frontmatter van de Markdown-pagina.

Mermaid-grafieken

Ansel maakt intensief gebruik van pipelines, en die worden het best beschreven met stroomdiagrammen. Mermaid.js wordt nu native ondersteund op Github en binnen Visual Studio Code en is daar uitstekend voor geschikt. Je kunt het hier visueel uitproberen  en de code van de grafieken kopiëren en plakken binnen Markdown-codeblokken zoals dit:

1    ```mermaid
2    graph TD
3        A[Christmas] -->|Get money| B(Go shopping)
4        B --> C{Let me think}
5        C -->|One| D[Laptop]
6        C -->|Two| E[iPhone]
7        C -->|Three| F[fa:fa-car Car]
8    ```

Dit geeft weer:

graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

Iconen van Font Awesome v5  worden ondersteund door de Ansel-hoofdwebsite en -documentatie, met de syntaxis fa:fa-YOUR-ICON-CODE zoals getoond in het bovenstaande voorbeeld. Gebruik de zoekmachine van Font Awesome v5  om de fa--code te krijgen van de iconen die je wilt gebruiken.

Mermaid-grafieken worden aan de clientzijde weergegeven in SVG op weergavegrootte en kunnen als tekst worden vertaald. Hugo is geconfigureerd om deze grafieken automatisch te detecteren en de javascript-bibliotheek alleen te laden wanneer dat nodig is. Github kan Mermaid-grafieken ook native weergeven bij het tonen van Markdown-bestanden.

De URL van pagina’s wijzigen

Soms is het zinvol om de inhoud te reorganiseren en het pad van sommige pagina’s te wijzigen. Om te voorkomen dat externe links breken, moet je de oude url van de nieuwe pagina vastleggen als een alias, in de frontmatter van de nieuwe pagina, zoals zo:

1aliases:
2    - /my-old-url/
3    - /another-even-older-url

Notities

RSS-feed

De documentatie heeft voorlopig een gelokaliseerde RSS-feed:

Dit is ongebruikelijk en is bedoeld om gebruikers te helpen wijzigingen en ontwikkelingen bij te houden, door zich te abonneren op de RSS-feed of door deze te koppelen aan bots.

De datum van de documentatiepagina’s die in de RSS-feed is ingesteld, is de lastmod-parameter, oftewel het tijdstip van de laatste wijziging. Omdat RSS geen jast modified date heeft, is dit het beste dat ik voorlopig heb gevonden.

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