O site web do Ansel é construído usando o Hugo 0.146 . Este é um gerador de sites estáticos que permite construir sites muito rápidos a partir de arquivos Markdown. Um modelo personalizado e muitos shortcodes personalizados foram construídos para o Ansel. Você precisará primeiro instalar a versão estendida do Hugo  no seu computador, embora pequenas alterações possam ser feitas diretamente nos arquivos Markdown sem construir o site inteiro.

Obtendo o código-fonte

Este site 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

Documentação do Ansel

A documentação do Ansel (Ansel Doc) é uma parte importante do site web do Ansel, mas como está sob uma licença diferente e é um fork da dtdocs GNU/GPL, não pode estar neste repositório. Queremos editar ambas como um conjunto, mas precisamos poder fazer commit delas separadamente em repositórios diferentes. Aqui está a solução.

A documentação do Ansel é obtida automaticamente como um módulo deste site no seu disco, como parte do script build-modules.sh acima, que também gera automaticamente as páginas traduzidas por meio de arquivos .po. Você a encontrará na pasta local do site, sob _vendor/github.com/aurelienpierreeng/ansel-doc/. Nenhum arquivo deve ser editado manualmente ali, isso é apenas para conteúdo gerado automaticamente.

Para editar a documentação do Ansel, faça

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

E então, edite o conteúdo (em inglês) de ansel-doc/content.

Edição interativa/Pré-visualização ao vivo

Iniciar o servidor de desenvolvimento

O Hugo permite que você abra uma versão renderizada do site, em um servidor de desenvolvimento local, para pré-visualizar suas alterações no seu navegador web.

Se você quiser editar apenas este site, execute a partir do diretório ./ansel-website:

1hugo server --disableFastRender

Se você quiser editar a documentação e ver os resultados em tempo real como parte deste site, depois de clonar a documentação (veja o passo anterior), execute a partir do diretório ./ansel-website:

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

Este truque carregará dinamicamente o módulo da documentação a partir da sua pasta local em vez do Github, o que significa que as alterações locais feitas na documentação aparecerão imediatamente no site principal por meio do seu servidor de desenvolvimento.

Atualizando as traduções dos sites

Veja Traduzindo.

Editando arquivos

Abrir o Obsidian

Abra ./ansel-website/content como um cofre (vault) do Obsidian. O Obsidian é capaz de resolver symlinks de pastas como se fossem pastas locais, então basicamente vemos o site como um todo, o que facilita fazer links internos entre a documentação e o site no editor.

Trabalhar no Obsidian é significativamente mais agradável do que trabalhar no VS Code para editar texto “de texto” (em oposição a texto de código em fonte monoespaçada), já que o editor é menos sobrecarregado e as fontes monoespaçadas cansam a vista depois de algumas horas em parágrafos inteiros.

  • O Markdown do Hugo não suporta call-outs do Obsidian . Você precisa usar as caixas de alerta mostradas acima como shortcodes do Hugo, mas elas não serão renderizadas no Obsidian,
  • O Hugo não suporta wikilinks do Obsidian , então você terá que se ater aos links Markdown usuais com caminhos relativos. Dito isso, o Obsidian fornece autocompletar de caminhos para eles.
  • O Obsidian não suporta listas de definição do Markdown , mas você ainda pode usá-las (elas simplesmente não serão renderizadas nas pré-visualizações),
  • O Obsidian não suporta IDs de cabeçalhos do Markdown ,

Porém:

  • O Obsidian suporta tags do Hugo no frontmatter Yaml, e as implementa de uma forma muito mais agradável que dá muito mais sentido ao encadeamento horizontal de conteúdo,
  • O Obsidian suporta aliases  do Hugo para redirecionamento de páginas,

Melhorando o entrelaçamento de conteúdo

O encadeamento horizontal, por meio de tags e links internos, é tão importante quanto o encadeamento vertical, seguindo árvores hierárquicas.

O Obsidian pode mostrar as tags disponíveis em todo o cofre para reutilização:

image

Ele também pode mostrar os melhores candidatos a links internos para cada palavra-chave na página, sob a seção recolhível “Unlinked mentions”:

image

Verificando a organização do conteúdo

Muitas vezes é difícil acompanhar o encadeamento de cabeçalhos em uma página Markdown, ao usar um editor de código típico. O Obsidian tem um widget de “outline” que permite manter o sumário à vista enquanto se escreve, para garantir que a hierarquia de cabeçalhos seja consistente :

image

Diretrizes

A documentação não é um manual nem um curso. Ela deve responder às perguntas :

  • “o que a interface gráfica está fazendo ?”
  • “como posso configurar o software ?”
  • “quais são os gargalos, ressalvas, limitações e armadilhas ?”.

A documentação espera que o leitor saiba o que fazer e explicará como fazer. Fluxos de trabalho de ponta a ponta, tutoriais, contexto científico etc., ou seja, o quê e o porquê, vão no site (recursos, fluxos de trabalho).

Pasta de conteúdo

A pasta de conteúdo está localizada no diretório content/ e a estrutura de pastas e subpastas produzirá a estrutura de seções e subseções no site. Os arquivos são escritos em Markdown e terminam com a extensão .md. Cada arquivo deve ter o seguinte cabeçalho (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---
  • O título é obrigatório. Por favor, use maiúsculas iniciais, como na língua real.
  • A data é definida uma única vez na criação da página e nunca deve mudar depois.
  • Atualize a data lastmod com a data de hoje toda vez que você atualizar um arquivo, e adicione-a se não estiver presente. Na internet, todo conteúdo é perecível e isso ajuda os leitores a deduzir se a página ainda é relevante no momento da leitura ou não.
  • draft definido como true significa que a página estará no repositório (no código-fonte), mas não aparecerá no front-end do site. Definido como false, a página fica visível no front-end.
  • As tags são opcionais, mas bem-vindas. O conteúdo é, por padrão, organizado verticalmente (hierarquicamente). As tags ajudam a criar links horizontais (temáticos) entre páginas. Tags relevantes poderiam ser “processamento de filme”, “HDR”, “monocromático” etc. Reutilize tags existentes prioritariamente. As tags devem sempre ser uma lista, mesmo quando há apenas uma (caso contrário, a construção do Hugo quebra).

Âncoras de página

Se você fizer links para âncoras de página, como /my-post.md#some-heading, certifique-se de não inserir uma barra / entre o slug da página e a hashtag # no seu código Markdown, ou então o arquivo será tomado por um diretório e não será encontrado.

Títulos (cabeçalhos)

Os títulos H1 (codificados como # Title em Markdown) são reservados para títulos de página e cada página deve ter exatamente um H1. A darktable-doc errou feio aqui ao usar H1 como títulos de seção, isso é tanto um erro de SEO quanto de acessibilidade. A web é semântica porque é projetada tanto para crawlers e leitores de tela quanto para humanos.

Esteja ciente de que o Hugo gera automaticamente links de âncora para os cabeçalhos, usando o texto do cabeçalho. Assim, evite usar símbolos nos cabeçalhos, especialmente barras (invertidas), que vão bagunçar os links de âncora.

Esteja ciente também de que essas âncoras de cabeçalhos podem ser usadas em outras páginas para fazer links diretos. Alterar o texto de um cabeçalho quebrará sua âncora e pode quebrar links externos. Para evitar quebrar âncoras em links externos, você pode alterar o texto do cabeçalho, mas forçar seu ID para o anterior, assim:

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

Isso preservará os links externos para /my-post/#my-old-heading. Veja os detalhes… 

Incorporando imagens

O Hugo trata as imagens como assets de página. Existem assets globais, para imagens reutilizadas em várias páginas, armazenados em uma subpasta assets/ da pasta principal do código-fonte, e assets locais, armazenados na mesma pasta que a página que os utiliza.

Assim como nos links internos, tudo precisa ser vinculado relativamente ao código-fonte tal como hospedado no sistema de arquivos local, não relativamente ao HTML compilado.

Veja como traduzir imagens.

Capturas de tela

As capturas de tela são o básico de qualquer documentação de software de front-end. Os mantenedores da darktable-doc as recusam sob a alegação de que não podem ser traduzidas e que logo ficarão obsoletas dada a frequência das mudanças na interface gráfica, mas isso é um enorme erro pedagógico. Mesmo no idioma errado, as capturas de tela ajudam a ver o que procurar na janela. Use-as. Elas ficarão obsoletas e talvez não sejam traduzidas, assim como o resto do texto.

Info, Avisos, Alertas

O tema Ansel do site principal fornece shortcodes para criar alertas e caixas de informação usando o sistema de templates do Hugo. Aqui está o código:

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

O conteúdo das caixas também pode usar Markdown.

Controles deslizantes de antes/depois

Novamente, usando o sistema de templates do Hugo, você pode exibir controles deslizantes de antes/depois onde ambas as imagens são sobrepostas. Isso se assemelha ao recurso de snapshot da sala escura do Ansel e do darktable e pode explicar de forma eficiente o efeito de módulos e configurações de uma maneira que os usuários podem reproduzir na interface gráfica. Ambas as imagens de antes e depois precisam ter o mesmo tamanho em pixels.

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

Matemática

A documentação suporta MathJax configurado para suporte à sintaxe LaTeX. Embora o objetivo não seja escrever literatura científica, existem alguns algoritmos feitos de multiplicações e adições que são mais facilmente mostrados como equações em vez de escrever blocos de texto.

O LaTeX inline deve ser delimitado por $, e as equações em bloco delimitadas por $$. Se você usar LaTeX, precisa notificar o Hugo para anexar o script do Mathjax na página definindo latex: true no cabeçalho/frontmatter da página Markdown.

Grafos Mermaid

O Ansel faz uso intenso de pipelines, e estes são melhor descritos com fluxogramas. O Mermaid.js agora é suportado nativamente no Github e dentro do Visual Studio Code e é ótimo para esse propósito. Você pode experimentá-lo visualmente aqui  e copiar e colar o código dos grafos dentro de blocos de código Markdown assim:

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

Isso renderiza:

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]

Os ícones do Font Awesome v5  são suportados pelo site principal e pela documentação do Ansel, usando a sintaxe fa:fa-YOUR-ICON-CODE como mostrado no exemplo acima. Use o mecanismo de busca do Font Awesome v5  para obter o código fa- dos ícones que você pode usar.

Os grafos Mermaid são renderizados no lado do cliente em SVG no tamanho de exibição e podem ser traduzidos como texto. O Hugo está configurado para detectar esses grafos automaticamente e carregar a biblioteca javascript apenas quando necessário. O Github também pode renderizar grafos Mermaid nativamente, ao exibir arquivos Markdown.

Alterando a URL das páginas

Às vezes, faz sentido reorganizar o conteúdo e alterar o caminho de algumas páginas. Para não quebrar links externos, você deve registrar a url antiga da nova página como um alias, no frontmatter da nova página assim:

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

Notas

Feed RSS

A documentação tem um feed RSS localizado, por enquanto :

Isso é incomum e serve para ajudar os usuários a acompanhar as mudanças e evoluções, ao assinar o feed RSS ou ao conectá-lo com bots.

A data das páginas de documentação definida no feed RSS é o parâmetro lastmod, ou seja, o horário da última modificação. Como o RSS não possui uma jast modified date, é o melhor que encontrei por enquanto.

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