2.2 Configuración

El primer archivo que puede ver es el archivo configuration o config en su directorio raíz, en el que puede establecer configuraciones globales de su sitio. Puede contener opciones como el título y la descripción de su sitio, así como otras opciones globales como enlaces a sus redes sociales, el menú de navegación y la URL base de su sitio web.

Al generar su sitio, Hugo buscará primero un archivo llamado config.toml. Si no puede encontrar uno, continuará buscando config.yaml.20 Como la mayoría de los temas de Hugo contienen sitios de ejemplo que envían archivos config.toml, y el formato TOML (Tom’s Obvious, Minimal Language) parece ser más popular en la comunidad de Hugo, hablaremos principalmente de config.toml aquí.

Recomendamos que utilice la sintaxis TOML solo para el archivo de configuración (también puede usar YAML si lo prefiere), y use YAML como el formato de datos para los metadatos de las páginas y publicaciones de R Markdown, porque R Markdown y blogdown son totalmente compatibles solo con YAML.21 Si tiene un sitio web que ya ha utilizado TOML, puede usar blogdown::hugo_convert (unsafe = TRUE) para convertir los datos de TOML a YAML, pero primero asegúrese de hacer una copia de seguridad del sitio web porque sobrescribirá los archivos de Markdown.

La documentación de Hugo no utiliza TOML o YAML consistentemente en sus ejemplos, lo que puede ser confuso. Preste mucha atención al formato de configuración al copiar ejemplos en su propio sitio web.

2.2.1 Sintaxis TOML

Si no está familiarizado con la sintaxis de TOML, le daremos una breve descripción general y podrá leer la documentación completa para conocer los detalles.

TOML se compone de pares clave-valor separados por signos iguales:

Cuando desee editar una configuración en el archivo TOML, simplemente cambie el valor. Los valores que son cadenas de caracteres deben estar entre comillas, mientras que los valores booleanos deben estar minúsculos y descubiertos.

Por ejemplo, si desea darle a su sitio el título “Mi Sitio Impresionante” y usar URL relativas en lugar de las URL absolutas predeterminadas, puede tener las siguientes entradas en su archivo config.toml.

La mayoría de las variables globales de su sitio web se ingresan en el archivo config.toml exactamente de esta manera.

Más adelante en su archivo config, puede observar algunos valores entre paréntesis como este:

Esta es una tabla en el lenguaje TOML y Hugo los usa para completar información en otras páginas dentro de su sitio. Por ejemplo, la tabla anterior rellenará la variable .Site.Social en las plantillas de su sitio (más información sobre esto en la sección ??).

Por último, puede encontrar algunos valores en corchetes dobles como este:

En TOML, los corchetes dobles se usan para indicar una matriz de tablas. Hugo interpreta esta información como un menú. Si el código anterior se encuentra en un archivo config.toml, el sitio web resultante tendrá enlaces a las páginas Blog, Categorías y Acerca de en el menú principal del sitio. La ubicación y el estilo de ese menú se especifican en otra parte, pero aquí se definen los nombres de las opciones de cada menú y los enlaces a cada sección.

El archivo config.toml es diferente para cada tema. Asegúrese de que cuando elija un tema, lea su documentación a fondo para comprender lo que hace cada una de las opciones de configuración (más sobre los temas en la sección 2.4).

2.2.2 Opciones

Todas las opciones incorporadas que puede establecer para Hugo se enumeran en https://gohugo.io/overview/configuration/. Puede cambiar cualquiera de estas opciones, excepto contentDir, que está codificado en content en blogdown. Nuestra recomendación general es que será mejor que no modifique los valores predeterminados a menos que comprenda las consecuencias. Enumeramos algunas opciones que pueden ser de su interés:

  • baseURL: Normalmente tiene que cambiar el valor de esta opción a la URL base de su sitio web. Algunos temas de Hugo pueden tenerlo configurado para http://replace-this-with-your-hugo-site.com/ o http://www.example.com/ en sus sitios de ejemplo, pero asegúrese de reemplazarlos con su propia URL (consulte el capítulo ?? y el apéndice C para obtener más información sobre la publicación de sitios web y la obtención de nombres de dominio). Tenga en cuenta que esta opción puede ser una URL con un subtrayecto, si su sitio web se publicará en una subruta de un nombre de dominio, e.g., http://www.example.com/docs/.

  • enableEmoji: Puede configurarlo en true para que pueda usar Emoticones Emoji como :smile: en Markdown.

  • permalinks: Reglas para generar enlaces permanentes de sus páginas. Por defecto, Hugo usa nombres de archivos completos bajo content/ para generar links, e.g., content/about.md será renderizado a public/about/index.html, y content/post/2015-07-23-foo.md será renderizado a public/post/2015-07-23-foo/index.html, entonces los enlaces reales son /about/ y /post/2015-07-23-foo/ en el sitio web. Aunque no es necesario establecer reglas personalizadas para enlaces permanentes, es común ver enlaces de la forma /YYYY/mm/dd/post-title/. Hugo le permite usar varias piezas de información sobre un archivo fuente para generar un enlace, como la fecha (año, mes y día), título y nombre de archivo, etc. El enlace puede ser independiente del nombre del archivo. Por ejemplo, puede pedirle a Hugo que presente páginas bajo content/post/ usando la fecha y el título de sus enlaces:

    Personalmente, le recomiendo que use la variable :slug22 En lugar de :títle:

    Esto se debe a que el título de su publicación puede cambiar, y es probable que no desee que el enlace a la publicación cambie; de lo contrario, debe redirigir el enlace anterior al nuevo enlace, y habrá otros tipos de problemas, como los comentarios de Disqus. La variable :slug vuelve a :title si un campo llamado slug no está establecido en los metadatos YAML de la publicación. Puede establecer un slug fijo para que el enlace a la publicación siempre sea fijo y tendrá la libertad de actualizar el título de su publicación.

    Puede encontrar una lista de todas las posibles variables que usted puede usar en la opción permalinks en https://gohugo.io/extras/permalinks/.

  • publishDir: El directorio bajo el cual quiere generar el sitio web.

  • theme: El nombre del directorio de Hugo bajo themes/.

  • ignoreFiles: Una lista de patrones de archivo (expresiones regulares) para Hugo con el fin de que ignore ciertos archivos cuando se construye el sitio. Recomiendo que especifique al menos estos patrones ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]. Debería ignorar los archivos .Rmd porque blogdown los compilará a .html, y le basta a Hugo usar los archivos .html. No hay necesidad de que Hugo construya archivos .Rmd, y actualmente Hugo no sabe cómo. Los directorios con sufijos _files y _cache deberían ser ignorados porque contienen archivos auxiliares una vez que un archivo Rmd se compila, y blogdown los almacenará. Hugo no los debería copiar de nuevo al directorio public/.

  • uglyURLs: Por defecto, Hugo genera URLs “limpias”. Esto puede ser un poco sorprendente y requiere que comprenda cómo funcionan las URL cuando su buscador obtiene una página de un servidor. Básicamente, Hugo genera foo/index.html para foo.md de forma predeterminada en lugar de foo.html, porque el primero le permite visitar la página a través de la URL limpia foo/ sin index.html. La mayoría de los servidores web entienden solicitudes como http://www.example.com/foo/ y presentan index.html bajo foo/. Si prefiere el mapeo estricto de *.md a *.html, puede habilitar las URL “feas” configurando uglyURLs en true.

  • hasCJKLanguage: Si su sitio web se encuentra principalmente en CJK (chino, coreano y japonés), le recomiendo que configure esta opción en true, para que el resumen automático y el recuento de palabras de Hugo funcionen mejor.

Además de las opciones incorporadas de Hugo, puede establecer otras opciones arbitrarias en config.toml. Por ejemplo, es muy común ver una opción llamada params, que se usa ampliamente en muchos temas de Hugo. Cuando vea una variable .Site.Params.FOO en un tema de Hugo, significa una opción FOO que se establece bajo [params] en config.toml, por ejemplo, .Site.Params.author es Frida Gomam con el siguiente archivo de configuración:

El objetivo de todas estas opciones es evitar cualquier problema de codificación en los temas de Hugo, de modo que los usuarios puedan editar fácilmente un único archivo de configuración para aplicar el tema a sus sitios web, en lugar de pasar por muchos archivos HTML y realizar cambios uno por uno.

  1. Hugo también admite config.json, pero blogdown no lo admite, por lo que no recomendamos que lo use.↩

  2. TOML tiene sus ventajas, pero creo que no son significativas en el contexto de los sitios web de Hugo. Es un dolor tener que conocer otro idioma, TOML, cuando YAML significa “Yet Another Markup Language”. No estoy seguro de si el cómic XKCD se aplica en este caso: https://xkcd.com/927/.↩

  3. Una slug es simplemente una cadena de caracteres que puede usar para identificar una publicación específica. Una slug no cambiará, incluso si el título cambia. Por ejemplo, si decide cambiar el título de su publicación de “Me encanta el blogdown” a “Por qué blogdown es el mejor paquete de la historia” y usó el título de la publicación en la URL, sus enlaces anteriores ahora se romperán. Si, en cambio, especifica la URL a través de un slug (algo así como “blogdown-love”), puede cambiar el título tantas veces como quiera y no terminará con enlaces rotos.↩