Strona Ansel jest zbudowana przy użyciu Hugo 0.146 . Jest to generator statycznych stron internetowych, który pozwala budować bardzo szybkie strony z plików Markdown. Dla Ansel stworzono niestandardowy szablon oraz wiele niestandardowych shortcode’ów. Najpierw musisz zainstalować rozszerzoną wersję Hugo  na swoim komputerze, choć drobne zmiany można wprowadzać bezpośrednio w plikach Markdown bez budowania całej strony.

Pobieranie kodu źródłowego

Ta strona

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

Dokumentacja Ansel

Dokumentacja Ansel jest ważną częścią strony Ansel, ale ponieważ podlega innej licencji i jest forkiem dtdocs na licencji GNU/GPL, nie może znajdować się w tym repozytorium. Chcemy edytować obie jako pakiet, ale musimy mieć możliwość commitowania ich osobno do różnych repozytoriów. Oto rozwiązanie.

Dokumentacja Ansel jest pobierana automatycznie jako moduł tej strony na Twój dysk w ramach skryptu build-modules.sh powyżej, który również automatycznie generuje przetłumaczone strony za pomocą plików .po. Znajdziesz ją w lokalnym folderze strony, w _vendor/github.com/aurelienpierreeng/ansel-doc/. Żaden plik nie powinien być tam edytowany ręcznie, to wyłącznie treść generowana automatycznie.

Aby edytować dokumentację Ansel, wykonaj

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

A następnie edytuj (angielską) treść w ansel-doc/content.

Edycja interaktywna / podgląd na żywo

Uruchamianie serwera deweloperskiego

Hugo pozwala otworzyć wyrenderowaną wersję strony na lokalnym serwerze deweloperskim, aby podejrzeć wprowadzane zmiany w przeglądarce internetowej.

Jeśli chcesz edytować tylko tę stronę, uruchom z katalogu ./ansel-website:

1hugo server --disableFastRender

Jeśli chcesz edytować dokumentację i widzieć wyniki w czasie rzeczywistym jako część tej strony, po sklonowaniu dokumentacji (patrz poprzedni krok) uruchom z katalogu ./ansel-website:

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

Ta sztuczka spowoduje dynamiczne wczytanie modułu dokumentacji z Twojego lokalnego folderu, a nie z GitHuba, co oznacza, że lokalne zmiany wprowadzone w dokumentacji natychmiast pojawią się na głównej stronie za pośrednictwem Twojego serwera deweloperskiego.

Aktualizowanie tłumaczeń stron internetowych

Zobacz Tłumaczenie.

Edytowanie plików

Otwieranie Obsidian

Otwórz ./ansel-website/content jako sejf (vault) Obsidian. Obsidian potrafi rozwiązywać dowiązania symboliczne folderów tak, jakby były folderami lokalnymi, więc w zasadzie widzimy stronę jako całość, co ułatwia tworzenie w edytorze wewnętrznych odnośników między dokumentacją a stroną.

Praca w Obsidian jest znacznie przyjemniejsza niż praca w VS Code przy edytowaniu „zwykłego" tekstu (w przeciwieństwie do tekstu kodu pisanego czcionką o stałej szerokości), ponieważ edytor jest mniej przeładowany, a czcionki o stałej szerokości męczą wzrok po kilku godzinach przy całych akapitach.

  • Markdown w Hugo nie obsługuje call-outów Obsidian . Musisz używać pokazanych powyżej ramek alertów jako shortcode’ów Hugo, ale nie będą się one renderować w Obsidian,
  • Hugo nie obsługuje wikilinków Obsidian , więc będziesz musiał trzymać się zwykłych odnośników Markdown ze ścieżkami względnymi. Warto dodać, że Obsidian zapewnia dla nich autouzupełnianie ścieżek.
  • Obsidian nie obsługuje list definicji Markdown , ale i tak możesz ich używać (po prostu nie będą renderowane w podglądach),
  • Obsidian nie obsługuje identyfikatorów nagłówków Markdown ,

Jednak:

  • Obsidian obsługuje tagi Hugo w nagłówku YAML (frontmatter) i implementuje je w znacznie przyjemniejszy sposób, który nadaje o wiele więcej sensu poziomemu linkowaniu treści,
  • Obsidian obsługuje aliasy  Hugo do przekierowywania stron,

Radzenie sobie z uszkodzonymi odnośnikami

Istnieje do tego rozszerzenie: https://github.com/graydon/obsidian-dangling-links . Po zainstalowaniu pokazuje ono odnośniki, które nie wskazują na żaden istniejący plik w całym sejfie, w tym na głównej stronie i w dokumentacji:

image

W widoku grafu węzłów uszkodzone odnośniki pojawiają się również według swojej ścieżki ../../stuff.md, a nie według nazwy pliku.

W edytorze każdej strony można zobaczyć, które strony linkują do aktualnie otwartej strony, wraz z kotwicą nagłówka, co jest przydatne przed zmianą nagłówków, a tym samym zniszczeniem wewnętrznych odnośników:

image

Poprawianie powiązania treści

Linkowanie poziome, poprzez tagi i wewnętrzne odnośniki, jest równie ważne jak linkowanie pionowe, podążające za hierarchicznymi drzewami.

Obsidian potrafi pokazać dostępne w całym sejfie tagi do ponownego wykorzystania:

image

Potrafi również pokazać najlepszych kandydatów na wewnętrzne odnośniki dla każdego słowa kluczowego na stronie, w rozwijanej sekcji „Unlinked mentions":

image

Sprawdzanie organizacji treści

Często trudno jest śledzić kolejność nagłówków na stronie Markdown przy korzystaniu z typowego edytora kodu. Obsidian ma widżet „outline", który pozwala mieć spis treści na oku podczas pisania, aby zapewnić spójność hierarchii nagłówków:

image

Wytyczne

Dokumentacja nie jest podręcznikiem ani kursem. Powinna odpowiadać na pytania:

  • „co robi GUI?"
  • „jak mogę skonfigurować oprogramowanie?"
  • „jakie są wąskie gardła, zastrzeżenia, ograniczenia i pułapki?".

Dokumentacja oczekuje, że czytelnik wie, co ma zrobić, i wyjaśnia, jak to zrobić. Kompletne procesy pracy od początku do końca, samouczki, tło naukowe itd., czyli co i dlaczego, trafiają na stronę (zasoby, procesy pracy).

Folder z treścią

Folder z treścią znajduje się w katalogu content/, a struktura folderów i podfolderów wygeneruje strukturę sekcji i podsekcji na stronie. Pliki są pisane w Markdown i mają rozszerzenie .md. Każdy plik powinien mieć następujący nagłówek (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---
  • Tytuł jest obowiązkowy. Używaj wielkich liter na początku, jak w prawdziwym języku.
  • Data jest ustawiana raz na zawsze przy tworzeniu strony i nie powinna się już nigdy zmieniać.
  • Aktualizuj datę lastmod na dzisiejszą za każdym razem, gdy aktualizujesz plik, i dodaj ją, jeśli jej nie ma. W internecie każda treść jest nietrwała, a to pomaga czytelnikom domyślić się, czy strona jest nadal aktualna w chwili czytania, czy nie.
  • draft ustawione na true oznacza, że strona będzie w repozytorium (w kodzie źródłowym), ale nie pojawi się na froncie strony. Ustawione na false, strona jest widoczna na froncie.
  • tags są opcjonalne, ale mile widziane. Treść jest domyślnie zorganizowana pionowo (hierarchicznie). Tagi pomagają tworzyć poziome (tematyczne) powiązania między stronami. Trafne tagi to na przykład „film processing", „HDR", „monochrome" itd. W pierwszej kolejności wykorzystuj istniejące tagi. Tagi powinny zawsze być listą, nawet gdy jest tylko jeden (w przeciwnym razie budowanie Hugo się psuje).

Odnośniki wewnętrzne

Odnośniki wewnętrzne powinny w miarę możliwości używać ścieżek względnych od bieżącego pliku, co nie jest domyślnym zachowaniem Hugo. Celem jest możliwość podążania za względnymi odnośnikami w lokalnym systemie plików z dowolnego nowoczesnego edytora tekstu, jak w każdym pliku README.md. Używamy własnego kodu, aby ponownie połączyć te względne odnośniki z plikami zgodnie ze strukturą strony Hugo (po kompilacji).

Podczas budowania strony odnośniki wewnętrzne są sprawdzane i zostanie zgłoszony błąd krytyczny (przerywający kompilację), jeśli nie można znaleźć strony wskazywanej przez odnośnik wewnętrzny. Musisz mieć je na oku. W konsoli mogą pojawiać się również błędy niekrytyczne (czyli WARNING [languages] REF_NOT_FOUND), ponieważ przekształcamy linker Hugo w niestandardowy sposób, ale te można zignorować.

Przykład odnośników wewnętrznych:

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

Kotwice stron

Jeśli tworzysz odnośniki do kotwic stron, jak /my-post.md#some-heading, upewnij się, że nie wstawiasz ukośnika / między slug strony a hasztag # w swoim kodzie Markdown, bo inaczej plik zostanie potraktowany jako katalog i nie zostanie znaleziony.

Odnośniki bezwzględne

Załóżmy, że chcesz utworzyć odnośnik do strony wsparcia. Oto wszystkie możliwości utworzenia odnośnika do tej strony:

  • [support](/support/) -> poprawne dla Hugo, ale działa dopiero po skompilowaniu strony, więc nie da się go łatwo debugować w edytorze kodu. proszę unikać
  • [support](/support.md) -> niepoprawne dla Hugo, zadziała jako efekt uboczny naszego niestandardowego przetwarzania odnośników, ale w ogóle nie da się go debugować w edytorze kodu. proszę unikać
  • [support](./support.md) -> niepoprawne dla Hugo, działa zgodnie z zamierzeniem naszego niestandardowego przetwarzania odnośników, jeśli jest wywoływane na przykład ze strony indeksu. proszę tego używać
  • [support](../support.md) -> niepoprawne dla Hugo, działa zgodnie z zamierzeniem naszego niestandardowego przetwarzania odnośników, jeśli jest wywoływane z podfolderu witryny, jak /contribute. proszę tego używać

Jeśli strona znajduje się w czymś, co Hugo nazywa pakietem strony lub sekcji , użyj odnośnika do jej pliku index.md lub _index.md.

Rób:
1[user manual](/doc/_index.md)
2[user manual](./doc/_index.md)
3[user manual](../../doc/_index.md)
Nie rób (nawet jeśli technicznie działa):
1[user manual](/doc)
2[user manual](/doc/)

Odnośniki zewnętrzne

Odnośniki zewnętrzne nie są sprawdzane, ponieważ zajmowałoby to zbyt dużo czasu podczas budowania, a budowanie i tak może odbywać się bez dostępu do sieci. Zawsze używaj https:// w zewnętrznych adresach URL, gdy to możliwe.

Tytuły (nagłówki)

Tytuły H1 (zakodowane jako # Tytuł w Markdown) są zarezerwowane dla tytułów stron i każda strona powinna mieć dokładnie jeden H1. darktable-doc mocno tu zawaliła, używając H1 jako tytułów sekcji — to błąd zarówno pod względem SEO, jak i dostępności. Sieć jest semantyczna, ponieważ jest projektowana dla robotów indeksujących i czytników ekranu tak samo, jak dla ludzi.

Pamiętaj, że Hugo automatycznie generuje kotwice odnośników dla nagłówków, używając tekstu nagłówka. Dlatego powstrzymaj się od używania symboli w nagłówkach, zwłaszcza (od)ukośników, które zepsują kotwice odnośników.

Pamiętaj również, że te kotwice nagłówków mogą być używane na innych stronach do tworzenia bezpośrednich odnośników. Zmiana tekstu nagłówka zepsuje jego kotwicę i może zepsuć odnośniki zewnętrzne. Aby uniknąć psucia kotwic w odnośnikach zewnętrznych, możesz zmienić tekst nagłówka, wymuszając jego identyfikator na poprzedni, w ten sposób:

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

To zachowa odnośniki zewnętrzne do /my-post/#my-old-heading. Zobacz szczegóły… 

Osadzanie obrazów

Hugo traktuje obrazy jako zasoby strony. Istnieją zasoby globalne, dla obrazów wykorzystywanych ponownie na kilku stronach, przechowywane w podfolderze assets/ głównego folderu kodu źródłowego, oraz zasoby lokalne, przechowywane w tym samym folderze co strona, która ich używa.

Podobnie jak w przypadku odnośników wewnętrznych, wszystko musi być linkowane względnie do kodu źródłowego w wersji hostowanej w lokalnym systemie plików, a nie względnie do skompilowanego HTML.

Zobacz jak tłumaczyć obrazy.

Zrzuty ekranu

Zrzuty ekranu są podstawą każdej dokumentacji oprogramowania z interfejsem graficznym. Opiekunowie darktable-doc odrzucają je pod pretekstem, że nie da się ich przetłumaczyć i wkrótce staną się przestarzałe z powodu częstotliwości zmian w GUI, ale to ogromny błąd pedagogiczny. Nawet w niewłaściwym języku zrzuty ekranu pomagają zobaczyć, czego szukać w oknie. Używaj ich. Staną się przestarzałe i mogą nie zostać przetłumaczone, tak samo jak reszta tekstu.

Informacje, ostrzeżenia, alerty

Motyw Ansel z głównej strony udostępnia shortcode’y do tworzenia alertów i ramek informacyjnych z użyciem systemu szablonów Hugo. Oto kod:

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

Treść ramek również może korzystać z Markdown.

Suwaki przed/po

Ponownie, korzystając z systemu szablonów Hugo, możesz wyświetlać suwaki przed/po, gdzie oba obrazy są nałożone na siebie. Przypomina to funkcję migawki (snapshot) ciemni w Ansel i darktable i potrafi skutecznie wyjaśnić działanie modułów i ustawień w sposób, który użytkownicy mogą odtworzyć w GUI. Oba obrazy, przed i po, muszą mieć ten sam rozmiar w pikselach.

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

Matematyka

Dokumentacja obsługuje MathJax skonfigurowany pod obsługę składni LaTeX. Choć celem nie jest pisanie literatury naukowej, istnieją pewne algorytmy złożone z mnożeń i dodawań, które łatwiej pokazać jako równania niż zapisywać w blokach tekstu.

Wbudowany LaTeX powinien być ujęty w $, a równania blokowe ujęte w $$. Jeśli używasz LaTeX, musisz poinformować Hugo, aby dołączył skrypt MathJax na stronie, ustawiając latex: true w nagłówku/frontmatterze strony Markdown.

Grafy Mermaid

Ansel intensywnie korzysta z potoków (pipeline), a te najlepiej opisywać za pomocą schematów blokowych. Mermaid.js jest teraz natywnie obsługiwany na GitHubie oraz w Visual Studio Code i świetnie się do tego nadaje. Możesz wypróbować go wizualnie tutaj  i skopiować kod grafów do bloków kodu Markdown w ten sposób:

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

To renderuje się jako:

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]

Ikony z Font Awesome v5  są obsługiwane przez główną stronę i dokumentację Ansel, z użyciem składni fa:fa-YOUR-ICON-CODE, jak pokazano w przykładzie powyżej. Użyj wyszukiwarki Font Awesome v5 , aby uzyskać kod fa- ikon, których chcesz użyć.

Grafy Mermaid są renderowane po stronie klienta w SVG w rozmiarze wyświetlania i mogą być tłumaczone jako tekst. Hugo jest skonfigurowany tak, aby automatycznie wykrywać te grafy i ładować bibliotekę JavaScript tylko wtedy, gdy jest potrzebna. GitHub również potrafi natywnie renderować grafy Mermaid podczas wyświetlania plików Markdown.

Zmiana adresów URL stron

Czasami ma sens reorganizacja treści i zmiana ścieżki niektórych stron. Aby nie zepsuć odnośników zewnętrznych, musisz zapisać stary adres URL nowej strony jako alias, w frontmatterze nowej strony, w ten sposób:

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

Uwagi

Kanał RSS

Dokumentacja ma zlokalizowany kanał RSS, na razie:

Jest to rozwiązanie nietypowe i ma pomóc użytkownikom śledzić zmiany oraz zmiany rozwojowe poprzez subskrypcję kanału RSS lub połączenie go z botami.

Datą stron dokumentacji ustawianą w kanale RSS jest parametr lastmod, czyli czas ostatniej modyfikacji. Ponieważ RSS nie posiada jast modified date, jest to najlepsze rozwiązanie, jakie na razie znalazłem.

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