El sitio web de Ansel está construido utilizando Hugo 0.146 . Este es un generador de sitios web estáticos que permite construir un sitio web muy rápido a partir de archivos Markdown. Se ha desarrollado una plantilla personalizada y muchos shortcodes personalizados para Ansel. Primero necesitarás instalar la versión extendida de Hugo  en tu computadora, aunque se pueden realizar cambios menores directamente en los archivos Markdown sin construir todo el sitio web.

Obteniendo el código fuente

This website

1$ git clone https://github.com/aurelienpierreeng/ansel-website
2# Almacenado, por ejemplo, en /home/user/dev/ansel-website
3$ cd ansel-website
4$ sh build-modules.sh

Ansel doc

Ansel Doc es una parte importante del sitio web de Ansel, pero debido a que está bajo una licencia diferente y se bifurcó de GNU/GPL dtdocs, no puede estar en este repositorio. Queremos editarlos ambos como un paquete pero necesitamos poder comprometerlos por separado en diferentes repositorios. Aquí está la solución.

El doc de Ansel se obtiene automáticamente como un módulo de este sitio web en tu disco como parte del script build-modules.sh mencionado anteriormente, que también genera automáticamente las páginas traducidas a través de archivos .po. Lo encontrarás en la carpeta local del sitio web, bajo _vendor/github.com/aurelienpierreeng/ansel-doc/. Ningún archivo debería ser editado manualmente allí, esto es solo para contenido autogenerado.

Para editar los documentos de Ansel, haz

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

Y luego, edita el contenido (en inglés) de ansel-doc/content.

Edición interactiva/Previsualización en vivo

Start the development server

Hugo te permite abrir una versión renderizada del sitio web, en un servidor de desarrollo local, para previsualizar tus cambios en tu navegador web.

Si solo quieres editar este sitio web, ejecuta desde el directorio ./ansel-website:

1hugo server --disableFastRender

Si quieres editar los documentos y ver los resultados en tiempo real como parte de este sitio web, después de clonar los documentos (ver paso anterior), ejecuta desde el directorio ./ansel-website:

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

Este truco cargará dinámicamente el módulo de documentos de tu carpeta local en lugar de hacerlo desde Github, lo que significa que los cambios locales hechos a los documentos aparecerán inmediatamente en el sitio web principal a través de tu servidor de desarrollo.

Updating websites translations

See Translating.

Edición de archivos

Abrir Obsidian

Abre ./ansel-website/content como un almacén de Obsidian. Obsidian es capaz de resolver enlaces simbólicos de carpetas como si fueran carpetas locales, por lo que básicamente vemos el sitio web como un todo, lo que facilita hacer enlaces internos entre el documento y el sitio web en el editor.

Trabajar en Obsidian es significativamente más agradable que trabajar en VS Code para editar texto “texto” (a diferencia del texto de código en monoespaciado), ya que el editor está menos sobrecargado y las fuentes monoespaciadas son cansadas para la vista después de un par de horas para párrafos completos.

Sin embargo:

  • Obsidian admite etiquetas de Hugo en frontmatter de Yaml, y las implementa de una manera mucho más elegante que da mucho más sentido al enlace de contenido horizontal,
  • Obsidian admite alias de Hugo  para la redirección de páginas,

Tratamiento de enlaces rotos

Hay una extensión para eso: https://github.com/graydon/obsidian-dangling-links . Una vez instalada, muestra los enlaces que apuntan a ningún archivo existente en todo el almacén, incluidos el sitio web principal y el documento:

image

En la vista del gráfico de nodos, los enlaces rotos también aparecen por su ruta ../../stuff.md en lugar de aparecer por su nombre de archivo.

En cada editor de página, es posible ver qué páginas están enlazando a la página que tienes abierta, incluidas las anclas de los encabezados, lo cual es útil antes de cambiar encabezados y, por lo tanto, destruir enlaces internos:

image

Mejora de la malla de contenido

El enlace horizontal, a través de etiquetas y enlaces internos, es tan importante como el enlace vertical, siguiendo árboles jerárquicos.

Obsidian puede mostrar las etiquetas disponibles en el almacén para reutilizar:

image

También puede mostrar los mejores enlaces internos candidatos para cada palabra clave en la página, bajo el desplegable de “Menciones no enlazadas”:

image

Checking content organization

A menudo es difícil seguir el encadenamiento de encabezados en una página de Markdown, cuando se usa un editor de código típico. Obsidian tiene un widget “esquema” que te permite mantener la tabla de contenidos a la vista al escribir, para asegurar que la jerarquía de encabezados sea consistente:

image

Directrices

La documentación no es un manual ni un curso. Debería responder a las preguntas:

  • “¿qué hace la GUI?”
  • “¿cómo puedo configurar el software?”
  • “¿cuáles son los cuellos de botella, advertencias, limitaciones y trampas?”.

La documentación espera que el lector sepa qué hacer y explicará cómo hacerlo. Los flujos de trabajo de principio a fin, tutoriales, antecedentes científicos, etc., es decir, el qué y el por qué van en el sitio web ( recursos, flujos de trabajo).

Content folder

La carpeta de contenido se encuentra en el directorio content/ y la estructura de carpetas y subcarpetas producirá la estructura de secciones y subsecciones en el sitio web. Los archivos están escritos en Markdown y terminan con la extensión .md. Cada archivo debe tener el siguiente encabezado (frontmatter):

 1---
 2título: Título de esta página
 3fecha: 2022-12-04T02:19:02+01:00
 4última modif: 2022-12-31
 5borrador: false
 6peso: 120
 7etiquetas:
 8    - color science
 9    - pipeline
10---
  • El título es obligatorio. Por favor, usa mayúsculas iniciales, como en el lenguaje real.
  • La fecha se establece una vez por todas en la creación de la página y nunca debe cambiar después.
  • Actualiza la fecha última modif con la fecha de hoy cada vez que actualices un archivo, y agrégala si no está presente. En Internet, cada contenido es perecedero y esto ayuda a los lectores a adivinar si la página sigue siendo relevante al momento de la lectura o no.
  • borrador configurado en true significa que la página estará en el repositorio (en el código fuente) pero no aparecerá en el front-end del sitio web. Configurado en false, la página es visible en el front-end.
  • etiquetas son opcionales pero bienvenidas. El contenido está, por defecto, organizado verticalmente (jerárquicamente). Las etiquetas ayudan a crear enlaces horizontales (temáticos) entre páginas. Las etiquetas relevantes podrían ser “procesamiento de película”, “HDR”, “monocromo”, etc. Reutiliza las etiquetas existentes como prioridad. Las etiquetas siempre deben ser una lista, incluso cuando solo hay una (de lo contrario, se rompe la compilación de Hugo).

Enlaces internos

Los enlaces internos deben usar rutas relativas desde el archivo actual siempre que sea posible, lo cual no es el comportamiento predeterminado de Hugo. El objetivo es poder seguir enlaces relativos en el sistema de archivos local desde cualquier editor de texto moderno, como en cualquier archivo README.md. Usamos nuestro propio código para reconectar esos enlaces relativos a archivos con la estructura del sitio web de Hugo (después de la compilación).

Al construir el sitio web, los enlaces internos se verifican y se generará un error crítico (abortando la compilación) si no se puede encontrar una página desde enlaces internos. Necesitas estar atento a ellos. Los errores no críticos (también conocidos como WARNING [languages] REF_NOT_FOUND) también pueden mostrarse en una consola porque torcemos el enlace de Hugo de una manera no estándar, pero esos pueden ser ignorados.

Example of internal links:

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

Anclas de página

Si haces enlaces a anclas de página, como /mi-post.md#algún-encabezado, asegúrate de no insertar una barra / entre la dirección de la página y la almohadilla # en tu código Markdown, de lo contrario, se tomará el archivo por un directorio y no se encontrará.

Enlaces absolutos

Supongamos que quieres enlazar a la página de soporte. Aquí están todas las posibilidades para crear un enlace a esa página:

  • [soporte](/support/) -> válido para Hugo, pero solo funciona después de que el sitio web se compile, por lo que no puede depurarse fácilmente en el editor de código. por favor evita
  • [soporte](/support.md) -> no válido para Hugo, funcionará como un efecto secundario de nuestro procesamiento de enlaces personalizado, pero no puede ser depurado en absoluto en el editor de código. por favor evita
  • [soporte](./support.md) -> no válido para Hugo, funciona según lo diseñado por nuestro procesamiento de enlaces personalizado si se llama desde la página de índice, por ejemplo. por favor usa esto
  • [soporte](../support.md) -> no válido para Hugo, funciona según lo diseñado por nuestro procesamiento de enlaces personalizado si se llama desde una subcarpeta del sitio, como /contribute. por favor usa esto

Si una página está en lo que Hugo llama un paquete de página o sección , por favor usa el enlace a su archivo index.md o _index.md.

Haz:
1[manual del usuario](/doc/_index.md)
2[manual del usuario](./doc/_index.md)
3[manual del usuario](../../doc/_index.md)
No (aunque técnicamente funcione):
1[manual del usuario](/doc)
2[manual del usuario](/doc/)

Enlaces externos

Los enlaces externos no se verifican porque tomaría demasiado tiempo al construir, y la construcción puede ocurrir sin acceso a la red de todos modos. Siempre usa https:// en las URL externas cuando sea posible.

Títulos (encabezados)

Los títulos H1 (codificados # Título en Markdown) están reservados para los títulos de página y cada página debe tener exactamente un H1. darktable-doc se equivocó gravemente aquí al usar H1 como títulos de sección, esto es tanto un error de SEO como de accesibilidad. La web es semántica porque está diseñada para rastreadores y lectores de pantalla tanto como para humanos.

Ten en cuenta que Hugo genera automáticamente enlaces de anclas para los encabezados, usando el texto del encabezado. Por lo tanto, abstente de usar símbolos en los encabezados, especialmente barras (inclinadas), que arruinarán los enlaces de anclas.

Also be aware that these headings anchors may be used in other pages to make direct links. Changing the text of an heading will break its anchor and may break external links. To avoid breaking anchors in external links, you can change the heading text but force their ID to the previous, like so:

1### Mi Nuevo Encabezado {#mi-viejo-encabezado}

Esto preservará enlaces externos a /mi-post/#mi-viejo-encabezado. Ver los detalles… 

Incrustar imágenes

Hugo trata las imágenes como recursos de página. Hay recursos globales, para imágenes reutilizadas en varias páginas, almacenadas en una subcarpeta assets/ de la carpeta principal del código fuente, y recursos locales, almacenados en la misma carpeta que la página que los utiliza.

Al igual que para los enlaces internos, todo necesita estar enlazado relativamente al código fuente según se hospeda en el sistema de archivos local, no relativo al HTML compilado.

Ver cómo traducir imágenes.

Capturas de pantalla

Las capturas de pantalla son la base de cualquier documentación de software front-end. Los mantenedores de docs de darktable las rechazan porque no se pueden traducir y quedarán obsoletas dado la frecuencia de los cambios en la GUI, pero es un gran error pedagógico. Incluso en el idioma incorrecto, las capturas de pantalla ayudan a ver qué buscar en la ventana. Úsalas. Quedarán obsoletas y puede que no se traduzcan, al igual que el resto del texto.

Info, Advertencias, Alertas

El tema Ansel del sitio web principal proporciona shortcodes para crear alertas y cajas de información usando el sistema de plantillas de Hugo. Aquí está el código:

1{{< advertencia >}}
2Aquí es donde dices lo que los usuarios deben tener en cuenta, porque lo que puede sonar como una buena idea en general puede ser realmente malo en algunas circunstancias.
3{{< /advertencia >}}
1{{< nota >}}
2Tu nota aquí.
3{{< /nota >}}
1{{< consejo >}}
2Tu consejo amigable aquí.
3{{< /consejo >}}
1{{< peligro >}}
2Aquí es donde recuerdas a los usuarios que son libres de hacer locuras pero habrá consecuencias.
3{{< /peligro >}}

El contenido de las cajas también puede usar Markdown.

Antes/después de los deslizadores

Nuevamente, usando el sistema de plantillas de Hugo, puedes mostrar deslizadores de antes/después donde ambas imágenes se superponen. Esto se asemeja a la característica de Ansel y darktable darkroom de instantáneas y puede explicar de manera eficaz el efecto de los módulos y configuraciones de una manera que los usuarios puedan reproducir en la GUI. Tanto las imágenes de antes como las de después necesitan tener el mismo tamaño en píxeles.

1{{< comparar después="./img-after.jpg" antes="./img-before.jpg" >}}
2Tu leyenda del deslizador aquí.
3{{< /comparar >}}

Matemáticas

Los documentos soportan MathJax configurado para el soporte sintáctico de LaTeX. Aunque el objetivo no es escribir literatura científica, hay algunos algoritmos hechos de multiplicaciones y sumas que son más fáciles de mostrar como ecuaciones en lugar de escribir bloques de texto.

LaTeX en línea debe estar encerrado en $, las ecuaciones en bloque encerradas en $$. Si usas LaTeX, necesitas notificar a Hugo para que agregue el script de Mathjax en la página configurando latex: true en el encabezado/frontmatter de la página Markdown.

Gráficos Mermaid

Ansel hace un uso intensivo de pipelines, y estos se describen mejor con diagramas de flujo. Mermaid.js ahora es compatible de forma nativa en Github y dentro de Visual Studio Code y es excelente para ese propósito. Puedes probarlo visualmente aquí  y copiar y pegar el código de los gráficos dentro de bloques de código Markdown como este:

1    ```mermaid
2    graph TD
3        A[Navidad] -->|Obtener dinero| B(Ir de compras)
4        B --> C{Déjame pensar}
5        C -->|Uno| D[Portátil]
6        C -->|Dos| E[iPhone]
7        C -->|Tres| F[fa:fa-car Coche]
8    ```

This renders:

graph TD
    A[Navidad] -->|Obtener dinero| B(Ir de compras)
    B --> C{Déjame pensar}
    C -->|Uno| D[Portátil]
    C -->|Dos| E[iPhone]
    C -->|Tres| F[fa:fa-car Coche]

Los iconos de Font Awesome v5  son compatibles con el sitio web principal y la documentación de Ansel, usando la sintaxis fa:fa-TU-CÓDIGO-DE-ICONO como se muestra en el ejemplo anterior. Usa el buscador de Font Awesome v5  para obtener el código fa- de los iconos que puedas usar.

Mermaid graphs are rendered client-side in SVG at display size and can be translated as text. Hugo is configured to detect these graphs automatically and load the javascript library only when needed. Github can also render Mermaid graphs natively, when displaying Markdown files.

Cambiar URL de páginas

A veces, tiene sentido reorganizar el contenido y cambiar la ruta de algunas páginas. Para no romper enlaces externos, debes registrar la URL vieja de la nueva página como un alias, en el frontmatter de la nueva página así:

1alias:
2    - /mi-url-vieja/
3    - /otra-url-aún-más-vieja

Notas

Fuente RSS

La documentación tiene una fuente RSS localizada, por ahora:

Esto es inusual y está destinado a ayudar a los usuarios a seguir los cambios y evoluciones, suscribiéndose a la fuente RSS o conectándola con bots.

La fecha de las páginas de documentación establecida en la fuente RSS es el parámetro última modif, es decir, el momento de la última modificación. Dado que RSS no tiene una última fecha modificada, es lo mejor que he encontrado por el momento.

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