Il sito web di Ansel è costruito usando Hugo 0.146 . Si tratta di un generatore di siti web statici che permette di costruire siti web molto veloci a partire da file Markdown. Per Ansel sono stati sviluppati un template personalizzato e molti shortcode personalizzati. Dovrai prima installare la versione extended di Hugo  sul tuo computer, anche se piccole modifiche possono essere fatte direttamente ai file Markdown senza costruire l’intero sito web.

Ottenere il codice sorgente

Questo sito web

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 è una parte importante del sito web di Ansel, ma poiché è soggetta a una licenza diversa e forkata da dtdocs GNU/GPL, non può stare in questo repository. Vogliamo modificarle entrambe come un pacchetto ma abbiamo bisogno di poterne fare il commit separatamente su repository diversi. Ecco la soluzione.

La doc di Ansel viene scaricata automaticamente come modulo di questo sito web sul tuo disco all’interno dello script build-modules.sh visto sopra, che genera automaticamente anche le pagine tradotte attraverso i file .po. La troverai nella cartella locale del sito web, sotto _vendor/github.com/aurelienpierreeng/ansel-doc/. Nessun file dovrebbe essere modificato manualmente lì, questo serve solo per contenuti generati automaticamente.

Per modificare la doc di Ansel, esegui

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

E poi, modifica il contenuto (in inglese) di ansel-doc/content.

Modifica interattiva/Anteprima dal vivo

Avviare il server di sviluppo

Hugo ti permette di aprire una versione renderizzata del sito web, su un server di sviluppo locale, per vedere l’anteprima delle tue modifiche nel tuo browser web.

Se vuoi modificare solo questo sito web, esegui dalla directory ./ansel-website:

1hugo server --disableFastRender

Se vuoi modificare la doc e vedere i risultati in tempo reale all’interno di questo sito web, dopo aver clonato la doc (vedi il passaggio precedente), esegui dalla directory ./ansel-website:

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

Questo trucco caricherà dinamicamente il modulo della doc dalla tua cartella locale anziché da Github, il che significa che le modifiche locali fatte alla doc appariranno immediatamente nel sito web principale attraverso il tuo server di sviluppo.

Aggiornare le traduzioni dei siti web

Vedi Tradurre.

Modificare i file

Aprire Obsidian

Apri ./ansel-website/content come un vault di Obsidian. Obsidian è in grado di risolvere i symlink delle cartelle come se fossero cartelle locali, così vediamo essenzialmente il sito web nel suo insieme, il che rende più facile creare collegamenti interni tra doc e sito web nell’editor.

Lavorare in Obsidian è sensibilmente più piacevole che lavorare in VS Code per modificare testo “testo” (in contrapposizione al testo di codice in monospazio), poiché l’editor è meno appesantito e i font monospazio affaticano la vista dopo un paio d’ore per interi paragrafi.

  • Il Markdown di Hugo non supporta i call-out di Obsidian . Devi usare i box di avviso mostrati sopra come shortcode di Hugo, ma non verranno renderizzati in Obsidian,
  • Hugo non supporta i wikilink di Obsidian , quindi dovrai attenerti ai normali collegamenti Markdown con percorsi relativi. Detto ciò, Obsidian fornisce l’auto-completamento dei percorsi per questi.
  • Obsidian non supporta le liste di definizione Markdown , ma puoi comunque usarle (semplicemente non verranno renderizzate nelle anteprime),
  • Obsidian non supporta gli ID delle intestazioni Markdown ,

Tuttavia:

  • Obsidian supporta i tag di Hugo nel frontmatter Yaml, e li implementa in un modo molto più piacevole che dà molto più senso al collegamento orizzontale dei contenuti,
  • Obsidian supporta gli alias  di Hugo per il reindirizzamento delle pagine,

Gestire i collegamenti interrotti

Esiste un’estensione per questo : https://github.com/graydon/obsidian-dangling-links . Una volta installata, mostra i collegamenti che puntano a nessun file esistente in tutto il vault, incluso il sito web principale e la doc :

image

Nella vista a grafo dei nodi, i collegamenti interrotti appaiono anche col loro percorso ../../stuff.md invece di apparire col loro nome di file.

In ogni editor di pagina, è possibile vedere quali pagine collegano la pagina attualmente aperta, incluso l’ancora dell’intestazione, il che è utile prima di cambiare le intestazioni e quindi distruggere i collegamenti interni :

image

Migliorare l’intreccio dei contenuti

Il collegamento orizzontale, attraverso tag e collegamenti interni, è tanto importante quanto il collegamento verticale, che segue alberi gerarchici.

Obsidian può mostrare i tag disponibili a livello di vault per il riutilizzo:

image

Può anche mostrare i migliori collegamenti interni candidati per ogni parola chiave nella pagina, sotto la sezione richiudibile “Unlinked mentions”:

image

Controllare l’organizzazione dei contenuti

Spesso è difficile seguire il concatenamento delle intestazioni in una pagina Markdown, quando si usa un tipico editor di codice. Obsidian ha un widget “outline” che permette di tenere in vista l’indice dei contenuti mentre si scrive, per garantire che la gerarchia delle intestazioni sia coerente :

image

Linee guida

La documentazione non è un manuale né un corso. Dovrebbe rispondere alle domande :

  • “cosa sta facendo la GUI ?”
  • “come posso configurare il software ?”
  • “quali sono i colli di bottiglia, gli avvertimenti, le limitazioni e le trappole ?”.

La documentazione si aspetta che il lettore sappia cosa fare e spiegherà come farlo. I flussi di lavoro dall’inizio alla fine, i tutorial, il background scientifico ecc., ovvero il cosa e il perché vanno sul sito web (risorse, flussi di lavoro).

Cartella dei contenuti

La cartella dei contenuti si trova nella directory content/ e la struttura di cartelle e sotto-cartelle produrrà la struttura di sezioni e sotto-sezioni sul sito web. I file sono scritti in Markdown e terminano con l’estensione .md. Ogni file dovrebbe avere la seguente intestazione (frontmatter):

 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---
  • Il titolo è obbligatorio. Usa le iniziali maiuscole, come nella lingua reale.
  • La data è impostata una volta per tutte alla creazione della pagina e non dovrebbe mai cambiare in seguito.
  • Aggiorna la data lastmod con la data odierna ogni volta che aggiorni un file, e aggiungila se non è presente. Su internet, ogni contenuto è deperibile e questo aiuta i lettori a intuire se la pagina è ancora rilevante al momento della lettura oppure no.
  • draft impostato su true significa che la pagina sarà nel repository (nel codice sorgente) ma non apparirà nel front-end del sito web. Impostato su false, la pagina è visibile nel front-end.
  • I tags sono opzionali ma benvenuti. Il contenuto è, per impostazione predefinita, organizzato verticalmente (gerarchicamente). I tag aiutano a creare collegamenti orizzontali (tematici) tra le pagine. Tag rilevanti potrebbero essere “elaborazione film”, “HDR”, “monocromatico”, ecc. Riutilizza in via prioritaria i tag esistenti. I tag dovrebbero sempre essere una lista, anche quando ce n’è uno solo (altrimenti la build di Hugo si rompe).

Collegamenti interni

I collegamenti interni dovrebbero usare percorsi relativi dal file corrente ogni volta che è possibile, il che non è il comportamento predefinito di Hugo. Lo scopo è poter seguire i collegamenti relativi sul file system locale da qualsiasi editor di testo moderno, come in qualsiasi file README.md. Usiamo il nostro codice per ricollegare questi collegamenti relativi ai file con la struttura del sito web Hugo (dopo la compilazione).

Durante la costruzione del sito web, i collegamenti interni vengono controllati e verrà generato un errore critico (che interrompe la compilazione) se una pagina non può essere trovata a partire dai collegamenti interni. Devi tenerli d’occhio. Errori non critici (ovvero WARNING [languages] REF_NOT_FOUND) possono anche apparire in una console perché deformiamo il linker di Hugo in modo non standard, ma questi possono essere ignorati.

Esempio di collegamenti interni:

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

Ancore di pagina

Se crei collegamenti ad ancore di pagina, come /my-post.md#some-heading, assicurati di non inserire una barra / tra lo slug della pagina e il cancelletto # nel tuo codice Markdown, altrimenti il file verrà scambiato per una directory e non verrà trovato.

Collegamenti assoluti

Supponiamo che tu voglia collegarti alla pagina supporto. Ecco tutte le possibilità per creare un collegamento a quella pagina:

  • [support](/support/) -> valido per Hugo, ma funziona solo dopo che il sito web è compilato, quindi non può essere facilmente debuggato in un editor di codice. evita per favore
  • [support](/support.md) -> non valido per Hugo, funzionerà come effetto collaterale della nostra elaborazione personalizzata dei collegamenti, ma non può essere debuggato affatto in un editor di codice. evita per favore
  • [support](./support.md) -> non valido per Hugo, funziona come previsto dalla nostra elaborazione personalizzata dei collegamenti se chiamato dalla pagina index, per esempio. usa questo per favore
  • [support](../support.md) -> non valido per Hugo, funziona come previsto dalla nostra elaborazione personalizzata dei collegamenti se chiamato da una sotto-cartella del sito, come /contribute. usa questo per favore

Se una pagina si trova in ciò che Hugo chiama un page o section bundle , usa per favore il collegamento al suo file index.md o _index.md.

Fai:
1[user manual](/doc/_index.md)
2[user manual](./doc/_index.md)
3[user manual](../../doc/_index.md)
Non fare (anche se tecnicamente funziona):
1[user manual](/doc)
2[user manual](/doc/)

Collegamenti esterni

I collegamenti esterni non vengono controllati perché richiederebbe troppo tempo in fase di costruzione, e la costruzione potrebbe comunque avvenire senza accesso alla rete. Usa sempre https:// negli URL esterni quando possibile.

Titoli (intestazioni)

I titoli H1 (codificati # Title in Markdown) sono riservati ai titoli di pagina e ogni pagina dovrebbe avere esattamente un H1. darktable-doc ha sbagliato alla grande qui usando gli H1 come titoli di sezione, questo è sia un errore SEO che di accessibilità. Il web è semantico perché è progettato per i crawler e i lettori di schermo tanto quanto per gli esseri umani.

Tieni presente che Hugo genera automaticamente i collegamenti ad ancora per le intestazioni, usando il testo dell’intestazione. Quindi, astieniti dall’usare simboli nelle intestazioni, specialmente le barre (rovesciate), che rovineranno i collegamenti ad ancora.

Tieni inoltre presente che queste ancore delle intestazioni possono essere usate in altre pagine per creare collegamenti diretti. Cambiare il testo di un’intestazione ne romperà l’ancora e potrebbe rompere collegamenti esterni. Per evitare di rompere le ancore nei collegamenti esterni, puoi cambiare il testo dell’intestazione ma forzarne l’ID a quello precedente, così:

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

Questo preserverà i collegamenti esterni a /my-post/#my-old-heading. Vedi i dettagli… 

Incorporare immagini

Hugo tratta le immagini come asset di pagina. Ci sono asset globali, per immagini riutilizzate su più pagine, memorizzati in una sotto-cartella assets/ della cartella principale del codice sorgente, e asset locali, memorizzati nella stessa cartella della pagina che li usa.

Come per i collegamenti interni, tutto deve essere collegato relativamente al codice sorgente ospitato sul file system locale, non relativamente all’HTML compilato.

Vedi come tradurre le immagini.

Screenshot

Gli screenshot sono le basi di qualsiasi documentazione di software front-end. I maintainer di darktable-doc li rifiutano con la motivazione che non possono essere tradotti e che presto saranno obsoleti data la frequenza dei cambiamenti della GUI, ma è un enorme errore pedagogico. Anche nella lingua sbagliata, gli screenshot aiutano a vedere cosa cercare nella finestra. Usali. Diventeranno obsoleti e potrebbero non essere tradotti, proprio come il resto del testo.

Info, Avvertimenti, Avvisi

Il tema Ansel del sito web principale fornisce shortcode per creare avvisi e box informativi usando il sistema di templating di Hugo. Ecco il codice:

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 >}}

Il contenuto dei box può usare anche il Markdown.

Slider prima/dopo

Di nuovo, usando il sistema di templating di Hugo, puoi mostrare slider prima/dopo in cui entrambe le immagini sono sovrapposte. Questo assomiglia alla funzione snapshot della camera oscura di Ansel & darktable e può spiegare in modo efficace l’effetto di moduli e impostazioni in un modo che gli utenti possono riprodurre nella GUI. Sia l’immagine prima che quella dopo devono avere la stessa dimensione in pixel.

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

Matematica

La doc supporta MathJax configurato per il supporto della sintassi LaTeX. Sebbene lo scopo non sia scrivere letteratura scientifica, ci sono alcuni algoritmi fatti di moltiplicazioni e addizioni che sono più facilmente mostrati come equazioni piuttosto che scrivendo blocchi di testo.

Il LaTeX inline dovrebbe essere racchiuso in $, le equazioni a blocco racchiuse in $$. Se usi LaTeX, devi notificare a Hugo di aggiungere lo script Mathjax alla pagina impostando latex: true nell’intestazione/frontmatter della pagina Markdown.

Grafici Mermaid

Ansel fa un uso intensivo delle pipeline, e queste sono descritte al meglio con i diagrammi di flusso. Mermaid.js è ora supportato nativamente su Github e all’interno di Visual Studio Code ed è ottimo per questo scopo. Puoi provarlo visivamente qui  e copiare-incollare il codice dei grafici all’interno dei blocchi di codice Markdown in questo modo:

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    ```

Questo renderizza:

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]

Le icone di Font Awesome v5  sono supportate dal sito web principale di Ansel e dalla documentazione, usando la sintassi fa:fa-YOUR-ICON-CODE come mostrato nell’esempio sopra. Usa il motore di ricerca di Font Awesome v5  per ottenere il codice fa- delle icone che potresti usare.

I grafici Mermaid vengono renderizzati lato client in SVG alla dimensione di visualizzazione e possono essere tradotti come testo. Hugo è configurato per rilevare automaticamente questi grafici e caricare la libreria javascript solo quando necessario. Anche Github può renderizzare nativamente i grafici Mermaid, quando visualizza i file Markdown.

Cambiare l’URL delle pagine

A volte, ha senso riorganizzare il contenuto e cambiare il percorso di alcune pagine. Per non rompere i collegamenti esterni, devi registrare il vecchio url della nuova pagina come alias, nel frontmatter della nuova pagina in questo modo:

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

Note

Feed RSS

La documentazione ha un feed RSS localizzato, per ora :

Questo è insolito e serve ad aiutare gli utenti a tenere traccia delle modifiche e delle evoluzioni, iscrivendosi al feed RSS o collegandolo a dei bot.

La data delle pagine di documentazione impostata nel feed RSS è il parametro lastmod, ovvero l’ora dell’ultima modifica. Poiché l’RSS non dispone di una jast modified date, per il momento è il meglio che ho trovato.

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