Le site web d’Ansel est construit à l’aide de Hugo 0.146 . C’est un générateur de sites web statiques qui permet de créer des sites très rapides à partir de fichiers Markdown. Un modèle personnalisé et beaucoup de shortcodes personnalisés ont été développés pour Ansel. Vous devrez d’abord installer la version étendue de Hugo  sur votre ordinateur, bien que de petits changements puissent être effectués directement dans les fichiers Markdown sans reconstruire l’ensemble du site.

Obtenir le code source

Ce site

1$ git clone https://github.com/aurelienpierreeng/ansel-website
2# Stocké par exemple dans /home/user/dev/ansel-website
3$ cd ansel-website
4$ sh build-modules.sh

Doc d’Ansel

Ansel Doc est une partie importante du site web d’Ansel, mais comme il est sous une licence différente et dérivé des dtdocs GNU/GPL, il ne peut pas être sur ce dépôt. Nous voulons modifier les deux en tant que pack mais nous devons être en mesure de les soumettre séparément sur différents dépôts. Voici la solution.

Ansel Doc est récupéré automatiquement en tant que module de ce site web sur votre disque dans le cadre du script build-modules.sh ci-dessus, qui génère également automatiquement les pages traduites via des fichiers .po. Vous le trouverez dans le dossier local du site web, sous _vendor/github.com/aurelienpierreeng/ansel-doc/. Aucun fichier ne doit être modifié manuellement à cet endroit, il s’agit uniquement de contenu auto-généré.

Pour modifier les documents Ansel, faites

1$ git clone https://github.com/aurelienpierreeng/ansel-doc
2# Stocké par exemple dans in /home/user/dev/ansel-doc
3$ cd ansel-doc

Et ensuite, modifiez le contenu (en anglais) de ansel-doc/content.

Édition interactive/Aperçu en direct

Démarrer le serveur de développement

Hugo vous permet d’ouvrir une version rendue du site web sur un serveur de développement local, pour prévisualiser vos modifications dans votre navigateur web.

Si vous voulez uniquement modifier ce site web, exécutez depuis le répertoire ./ansel-website :

1hugo server --disableFastRender

Si vous voulez modifier les documents et voir les résultats en temps réel en tant que partie de ce site web, après avoir cloné les documents (voir l’étape précédente), exécutez depuis le répertoire ./ansel-website :

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

Cette astuce chargera dynamiquement le module de documents depuis votre dossier local plutôt que depuis Github, ce qui signifie que les modifications locales apportées aux documents apparaîtront immédiatement dans le site principal via votre serveur de développement.

Mettre à jour la traduction des sites web

Voir Traduire.

Modifier les fichiers

Ouvrir Obsidian

Ouvrez ./ansel-website/content en tant que coffre fort dans Obsidian. Obsidian est capable de résoudre les liens symboliques de dossiers comme s’il s’agissait de dossiers locaux, donc on voit essentiellement le site web dans son ensemble, ce qui facilite la création de liens internes entre le document et le site web dans l’éditeur.

Travailler dans Obsidian est nettement plus agréable que de travailler dans VS Code pour éditer du texte “texte” (par opposition au texte de code en monospace), car l’éditeur est moins encombré et les polices monospace fatiguent les yeux après quelques heures pour des paragraphes entiers.

  • Le format Markdown de Hugo ne prend pas en charge les call-outs Obsidian . Vous devez utiliser les boîtes d’alerte montrées ci-dessus comme raccourcis Hugo, mais elles ne seront pas rendues dans Obsidian,
  • Hugo ne supporte pas les liens Wiki d’Obsidian , alors vous devrez vous en tenir aux liens Markdown habituels avec des chemins relatifs. Cela dit, Obsidian offre l’auto-complétion des chemins pour ceux-ci.
  • Obsidian ne prend pas en charge les listes de définition Markdown , mais vous pouvez toujours les utiliser (elles ne seront tout simplement pas rendues en prévisualisation),
  • Obsidian ne supporte pas les Identifiants de titres Markdown ,

Cependant :

  • Obsidian prend en charge les balises Hugo dans le frontmatter Yaml, et les implémente de manière beaucoup plus élégante qui donne beaucoup plus de sens au lien horizontal de contenu,
  • Obsidian prend en charge les alias Hugo  pour la redirection des pages,

Gérer les liens brisés

Il existe une extension pour cela : https://github.com/graydon/obsidian-dangling-links . Une fois installée, elle montre les liens qui pointent vers aucun fichier existant à travers tout le coffre, y compris le site web principal et le document :

image

Dans la vue du graphe de nœud, les liens brisés apparaissent également par leur chemin ../../stuff.md au lieu d’apparaître par leur nom de fichier.

Dans chaque éditeur de page, il est possible de voir quelles pages renvoient à la page actuellement ouverte, y compris l’ancre des titres, ce qui est utile avant de changer de titres et ainsi détruire les liens internes :

image

Améliorer la connexion du contenu

Les liens horizontaux, par des balises et des liens internes, sont tout aussi importants que les liens verticaux, suivant des arbres hiérarchiques.

Obsidian peut afficher les balises disponibles dans l’ensemble du coffre pour être réutilisées :

image

Il peut également afficher les meilleurs candidats de liens internes pour chaque mot-clé de la page, sous la section “Mentions non liées” repliable :

image

Vérifier l’organisation du contenu

Il est souvent difficile de suivre la liaison des titres dans une page Markdown, lors de l’utilisation d’un éditeur de code typique. Obsidian a un widget “outline” qui permet de garder la table des matières en vue lors de la rédaction, pour assurer que la hiérarchie des titres est cohérente :

image

Lignes directrices

La documentation n’est pas un manuel ou un cours. Elle doit répondre aux questions :

  • “que fait l’interface graphique ?”
  • “comment puis-je configurer le logiciel ?”
  • “quels sont les goulots d’étranglement, les mises en garde, les limites et les pièges ?”.

La documentation suppose que le lecteur sait quoi faire et expliquera comment le faire. Les flux de travail de bout en bout, les tutoriels, le contexte scientifique, etc., c’est-à-dire le quoi et le pourquoi vont sur le site web ( ressources, flux de travail).

Répertoire du contenu

Le dossier de contenu se trouve dans le répertoire content/ et la structure des dossiers et sous-dossiers produira la structure des sections et sous-sections sur le site web. Les fichiers sont écrits en Markdown et se terminent par l’extension .md. Chaque fichier doit avoir l’en-tête suivant (frontmatter) :

 1---
 2title: Ce titre de page
 3date: 2022-12-04T02:19:02+01:00
 4lastmod: 2022-12-31
 5draft: false
 6weight: 120
 7tags:
 8    - science des couleurs
 9    - pipeline
10---
  • Le titre est obligatoire. Veuillez utiliser des majuscules initiales, comme en langue réelle.
  • La date est fixée une fois pour toutes lors de la création de la page et ne doit jamais changer par la suite.
  • Mettez à jour la date lastmod avec la date du jour à chaque fois que vous mettez à jour un fichier, et ajoutez-la si elle n’est pas présente. Sur internet, tout contenu est périssable et cela aide les lecteurs à deviner si la page est encore pertinente au moment de la lecture ou non.
  • draft mis à true signifie que la page sera dans le dépôt (dans le code source) mais n’apparaîtra pas sur l’interface du site web. Mis à false, la page est visible sur l’interface.
  • Les tags sont optionnels mais bienvenus. Le contenu est, par défaut, organisé verticalement (hiérarchiquement). Les tags aident à créer des liens horizontaux (thématiques) entre les pages. Les tags pertinents pourraient être “traitement de film”, “HDR”, “monochrome”, etc. Réutilisez les tags existants en priorité. Les tags devraient toujours être une liste, même lorsqu’il n’y en a qu’un (sinon la construction de Hugo échoue).

Liens internes

Les liens internes doivent utiliser des chemins relatifs à partir du fichier courant chaque fois que possible, ce qui n’est pas le comportement par défaut de Hugo. Le but est de pouvoir suivre les liens relatifs sur le système de fichiers local depuis n’importe quel éditeur de texte moderne, comme dans n’importe quel fichier README.md. Nous utilisons notre propre code pour reconnecter ces liens relatifs aux fichiers avec la structure du site web Hugo (après compilation).

Lors de la construction du site web, les liens internes sont vérifiés et une erreur critique (également connue sous le nom de WARNING [languages] REF_NOT_FOUND) peut aussi être affichée à la console parce que nous modifions le linker Hugo de manière non standard, mais elles peuvent être ignorées.

Exemple de lien interne :

1[Filmic](../../module-reference/processing-modules/filmic-rgb.md)
2[Filmic](./filmic-rgb.md)
3[Some page](./section/index.md)

Ancrages de page

Si vous faites des liens vers des ancres de page, comme /my-post.md#some-heading, assurez-vous de ne pas insérer de barre oblique / entre le slug de la page et le hashtag # dans votre code Markdown, sinon le fichier sera pris pour un répertoire et ne sera pas trouvé.

Liens absolus

Disons que vous souhaitez créer un lien vers la page support. Voici toutes les possibilités pour créer un lien vers cette page :

  • [support](/support/) -> valide pour Hugo, mais fonctionne seulement après la compilation du site, donc ne peut pas être débogué facilement dans un éditeur de code. à éviter, s’il vous plaît
  • [support](/support.md) -> invalide pour Hugo, fonctionnera comme effet secondaire de notre traitement des liens personnalisé, mais ne peut pas être débogué du tout dans un éditeur de code. à éviter, s’il vous plaît
  • [support](./support.md) -> invalide pour Hugo, fonctionne comme prévu par notre traitement de lien personnalisé si appelé depuis la page index, par exemple. à utiliser, s’il vous plaît
  • [support](../support.md) -> invalide pour Hugo, fonctionne comme prévu par notre traitement de lien personnalisé si appelé depuis un sous-dossier du site, comme /contribute. à utiliser, s’il vous plaît

Si une page se trouve dans ce que Hugo appelle un bundle de page ou de section , veuillez utiliser le lien vers son fichier index.md ou _index.md.

À faire :
1[user manual](/doc/_index.md)
2[user manual](./doc/_index.md)
3[user manual](../../doc/_index.md)
Ne fait pas (même si cela fonctionne techniquement):
1[user manual](/doc)
2[user manual](/doc/)

Liens externes

Les liens externes ne sont pas vérifiés car cela prendrait trop de temps lors de la construction, et la construction peut se faire sans accès réseau de toute façon. Utilisez toujours https:// dans les URL externes lorsque c’est possible.

Titres (intitulés)

Les titres H1 (encodés # Titre en Markdown) sont réservés aux titres de page et chaque page doit avoir exactement un H1. darktable-doc a sérieusement échoué ici en utilisant les H1 comme titres de section, c’est à la fois une erreur de SEO et d’accessibilité. Le web est sémantique car il est conçu pour les robots d’exploration et les lecteurs d’écran autant que pour les humains.

Soyez conscient que Hugo génère automatiquement des liens d’ancrage pour les intitulés, en utilisant le texte de l’intitulé. Par conséquent, abstenez-vous d’utiliser des symboles dans les intitulés, en particulier les barres (inverses) qui perturberont les liens d’ancrage.

Sachez également que ces ancres de titres peuvent être utilisées dans d’autres pages pour créer des liens directs. Modifier le texte d’un titre cassera son ancre et pourrait casser des liens externes. Pour éviter de casser les ancres dans les liens externes, vous pouvez changer le texte du titre mais forcer leur ID à celui précédent, comme ceci :

1### Mon Nouveau Titre {#mon-ancien-titre}

Cela préservera les liens externes vers /mon-post/#mon-ancien-titre. Voir les détails… 

Incorporer des images

Hugo traite les images comme des ressources de pages. Il existe des ressources globales, pour les images réutilisées sur plusieurs pages, stockées dans un sous-dossier assets/ du dossier principal du code source, et des ressources locales, stockées dans le même dossier que la page qui les utilise.

Comme pour les liens internes, tout doit être lié relativement au code source tel qu’hébergé sur le système de fichiers local, et non relativement au HTML compilé.

Voir comment traduire des images.

Captures d’écran

Les captures d’écran sont la base de toute documentation de logiciel frontal. Les mainteneurs de darktable-doc les refusent au motif qu’elles ne peuvent pas être traduites et qu’elles seront bientôt obsolètes étant donné la fréquence des changements d’interface graphique, mais c’est une énorme erreur pédagogique. Même dans la mauvaise langue, les captures d’écran aident à voir ce qu’il faut rechercher dans la fenêtre. Utilisez-les. Elles deviendront obsolètes et peuvent ne pas être traduites, tout comme le reste du texte.

Infos, Avertissements, Alertes

Le thème Ansel du site web principal fournit des shortcodes pour créer des boîtes d’alerte et d’info à l’aide du système de modélisation de Hugo. Voici le code :

1{{< warning >}}
2C'est là où vous dites ce que les utilisateurs doivent savoir, car ce qui peut sembler une bonne idée en général peut être vraiment mauvais dans certaines circonstances.
3{{< /warning >}}
1{{< note >}}
2Votre note ici.
3{{< /note >}}
1{{< advice >}}
2Votre conseil amical ici.
3{{< /advice >}}
1{{< danger >}}
2C'est là où vous rappelez aux utilisateurs qu'ils sont libres de faire des bêtises mais qu'il y aura des conséquences.
3{{< /danger >}}

Le contenu des boîtes peut également utiliser Markdown.

Curseurs avant/après

Encore une fois, utilisant le système de modélisation de Hugo, vous pouvez afficher des curseurs avant/après où les deux images sont superposées. Cela ressemble à la fonctionnalité d’instantané Ansel & darktable darkroom et peut efficacement expliquer l’effet des modules et des paramètres d’une manière que les utilisateurs peuvent reproduire dans l’interface graphique. Les images avant et après doivent avoir la même taille en pixels.

1{{< compare après="./img-after.jpg" avant="./img-before.jpg" >}}
2Votre légende de curseur va ici.
3{{< /compare >}}

Maths

Les documentations prennent en charge MathJax configuré pour le support de la syntaxe LaTeX. Bien que le but ne soit pas d’écrire de la littérature scientifique, certains algorithmes faits de multiplications et d’additions sont plus facilement montrés sous forme d’équations plutôt que d’écrire des blocs de texte.

Le LaTeX en ligne doit être encadré par $, les équations en bloc encadrées par $$. Si vous utilisez LaTeX, vous devez informer Hugo d’ajouter le script Mathjax sur la page en définissant latex: true dans l’en-tête/frontmatter de la page Markdown.

Graphiques Mermaid

Ansel fait un usage intensif des pipelines, et ceux-ci sont mieux décrits avec des organigrammes. Mermaid.js est maintenant supporté nativement sur Github et au sein de Visual Studio Code et est parfait pour cela. Vous pouvez l’essayer visuellement ici  et copier-coller le code des graphiques dans des blocs de code Markdown comme ceci :

1    ```mermaid
2    graph TD
3        A[Noël] -->|Obtenez de l'argent| B(Faire du shopping)
4        B --> C{Laissez-moi réfléchir}
5        C -->|Un| D[Ordinateur portable]
6        C -->|Deux| E[iPhone]
7        C -->|Trois| F[fa:fa-car Voiture]
8    ```

Cela rend :

graph TD
    A[Noël] -->|Obtenez de l'argent| B(Faire du shopping)
    B --> C{Laissez-moi réfléchir}
    C -->|Un| D[Ordinateur portable]
    C -->|Deux| E[iPhone]
    C -->|Trois| F[fa:fa-car Voiture]

Les icônes de Font Awesome v5  sont prises en charge par le site web principal et la documentation Ansel, utilisant la syntaxe fa:fa-CODE-DE-VOTRE-ICONE comme montré dans l’exemple ci-dessus. Utilisez le moteur de recherche Font Awesome v5  pour obtenir le code fa- des icônes que vous pouvez utiliser.

Les graphiques Mermaid sont rendus côté client en SVG à la taille d’affichage et peuvent être traduits en texte. Hugo est configuré pour détecter automatiquement ces graphiques et charger la bibliothèque javascript uniquement lorsque nécessaire. GitHub peut également rendre les graphiques Mermaid de manière native, lors de l’affichage des fichiers Markdown.

Changer les URL des pages

Parfois, il est logique de réorganiser le contenu et de changer le chemin de certaines pages. Pour ne pas casser les liens externes, vous devez enregistrer l’ancienne URL de la nouvelle page en tant qu’alias, dans le frontmatter de la nouvelle page comme ceci :

1aliases:
2    - /mon-ancienne-url/
3    - /une-autre-mêm

Notes

Flux RSS

La documentation dispose d’un flux RSS localisé pour le moment :

C’est inhabituel et vise à aider les utilisateurs à suivre les modifications et évolutions, en s’abonnant au flux RSS ou en le connectant avec des bots.

La date des pages de documentation fixée dans le flux RSS est le paramètre lastmod, c’est-à-dire l’heure de la dernière modification. Comme le RSS n’a pas de date de dernière modification, c’est le meilleur que j’ai trouvé pour l’instant.

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