Guía completa sobre series

Una serie organiza publicaciones relacionadas en orden secuencial, similar a los capítulos de un libro. A diferencia de las etiquetas, que simplemente agrupan contenido relacionado, las series sugieren un orden específico de lectura de principio a fin.

Las publicaciones dentro de una serie no necesitan publicarse de forma consecutiva; la función de series reúne publicaciones temáticamente vinculadas en una secuencia coherente.

El siguiente diagrama ilustra cómo las publicaciones de la serie (3, 5 y 8) existen dentro del flujo principal del blog mientras mantienen su propia secuencia ordenada dentro de Serie 1.

    flowchart
    subgraph main[BLOG]
        P1[Post 1]
        P2[P2]
        P3[P3]
        P4[P4]
        P5[P5]
        P6[P6]
        P7[P7]
        P8[P8]
        P9[P9]
    end
    subgraph series1[SERIE 1]
        PS1["Post Serie 1 (=P3)"]
        PS2["Post Serie 2 (=P5)"]
        PS3["Post Serie 3 (=P8)"]
    end
    P3 o-.-o PS1
    P5 o-.-o PS2
    P8 o-.-o PS3

Inicio rápido

1. Crea un directorio para tu serie

2. Crea _index.md en el directorio de la serie

3. Configura el front matter de _index.md:

   title = "Aprendiendo Rust"
   template = "series.html"
   sort_by = "slug"
   transparent = true
   
   [extra]
   series = true
   

4. Crea tus artículos de la serie en este directorio

¿Quieres saber más? ¡Sigue leyendo!

¿Cómo funcionan las series?

Una serie es simplemente una sección que tabi maneja de manera especial. Para más detalles sobre secciones, consulta la documentación de Zola.

Tomando el ejemplo del diagrama anterior, la estructura de directorios sería así:

content/
    _index.md
    blog/
        _index.md
        post1/
            index.md
        post2/
            index.md
        post4/
            index.md
        post6/
            index.md
        post7/
            index.md
        post9/
            index.md
        serie1/
            _index.md
            post3/
                index.md
            post5/
                index.md
            post8/
                index.md

Para crear una serie, necesitas:

1. Usar la plantilla series.html
2. Establecer series = true en la configuración [extra] de la sección
3. Activar transparent = true para integrar las publicaciones de la serie con la sección del blog principal

La página principal de la serie muestra un resumen seguido de una lista de todas las publicaciones en la serie:

Saltar a las publicaciones

Si el contenido de una serie (el Markdown después del frontmatter en _index.md) supera los 2000 caracteres, aparece un enlace “Saltar a publicaciones” junto al título de la serie.

Para forzar la activación o desactivación de esta función, configura show_jump_to_posts en la sección [extra] de tu sección de series o en config.toml. Esta configuración sigue la jerarquía.

Páginas de series y orden

Todas las páginas en la sección de series serán páginas de serie. Las páginas se ordenarán según el sort_by de la sección.

Aunque las series mantienen su propio orden interno, permanecen independientes del flujo cronológico de la sección principal (por ejemplo, blog/) gracias a la configuración transparent.

Opciones de orden

Elige entre estos métodos de orden, cada uno con sus ventajas:

Indexación de páginas

Las páginas en una serie se indexan empezando desde 1, siguiendo su orden sort_by. Para invertir la indexación (haciendo que la primera página tenga el índice más alto), añade esta configuración a _index.md o config.toml:

[extra]
post_listing_index_reversed = true  # Por defecto es false si no se configura

Esta configuración sigue la jerarquía.

Plantillas de introducción y conclusión

Los artículos de una serie pueden tener secciones automáticas de introducción y conclusión. Estas se configuran en el _index.md de tu serie. Un ejemplo básico:

[extra.series_intro_templates]
default = "Este artículo es parte de la serie $SERIES_HTML_LINK."

[extra.series_outro_templates]
default = "¡Gracias por leer la parte $SERIES_PAGE_INDEX de $SERIES_HTML_LINK!"

Las secciones de introducción y conclusión tienen sus propias clases CSS (series-page-intro y series-page-outro), lo que te permite personalizar su apariencia mediante CSS personalizado.

Tipos de plantillas

El sistema de series usa diferentes plantillas según la posición del artículo en la serie:

• next_only - Usado para el primer artículo (tiene artículo siguiente pero no anterior)
• middle - Usado para artículos con artículos anterior y siguiente
• prev_only - Usado para el último artículo (tiene artículo anterior pero no siguiente)
• default - Plantilla por defecto usada cuando no existe una plantilla específica para la posición

El sistema determina automáticamente qué plantilla usar según la posición del artículo. Las plantillas se definen en la configuración de la serie (_index.md), como extra.series_intro_templates y extra.series_outro_templates:

[extra.series_intro_templates]
next_only = "¡Bienvenido a la parte 1! Siguiente: $NEXT_HTML_LINK"
middle = "Anterior: $PREV_HTML_LINK | Siguiente: $NEXT_HTML_LINK"
prev_only = "¡El capítulo final! Anteriormente: $PREV_HTML_LINK"
default = "Parte $SERIES_PAGE_INDEX de $SERIES_PAGES_NUMBER"

Todas las plantillas son opcionales. La selección de plantillas sigue un sistema de prioridad:

1. Si existe una plantilla específica para la posición (next_only, middle, o prev_only), se usará esa
2. Si no, se usa la plantilla default
3. Si no se define ninguna plantilla, no se mostrará información de la serie

Mira el ejemplo de plantilla para ver un ejemplo más elaborado.

Ubicación en el contenido

Por defecto:

• Las introducciones de serie aparecen al inicio de tu artículo
• La conclusión aparece al final (antes de las notas al pie, si las hay)

Puedes controlar exactamente dónde aparecen usando <!-- series_intro --> y <!-- series_outro --> en tu Markdown:

Este párrafo aparece antes de la introducción de la serie.

<!-- series_intro -->

Contenido principal del artículo.

<!-- series_outro -->

## Recursos de aprendizaje

Contenido adicional...

[^1]: Las notas al pie siempre aparecerán al final.

Variables

Las plantillas de series usan un sistema flexible de variables que te permite:

1. Hacer referencia a información de la serie (título, enlaces)
2. Añadir navegación entre artículos
3. Mostrar indicadores de progreso
4. Incluir información personalizada usando tus propias variables

Las variables son marcadores que comienzan con $ y se reemplazan con contenido real cuando se construye tu sitio. Por ejemplo, $SERIES_HTML_LINK se convierte en un enlace clicable a la página índice de tu serie.

Hay tres tipos de variables:

• Variables básicas de serie: Información general sobre la serie
• Variables de navegación: Enlaces a artículos anterior/siguiente
• Variables personalizadas: Tus propios marcadores para información adicional

Variables básicas de serie

Variables de navegación

Referencia al primer artículo

Ejemplo de plantilla

# Introducción.
[extra.series_intro_templates]
next_only = """
¡Bienvenido a $SERIES_HTML_LINK! Esta serie de $SERIES_PAGES_NUMBER partes te enseñará Rust desde cero.

Siguiente: $NEXT_HTML_LINK - $NEXT_DESCRIPTION
"""

middle = """
📚 Parte $SERIES_PAGE_INDEX de $SERIES_PAGES_NUMBER en $SERIES_HTML_LINK

Anterior: $PREV_HTML_LINK
Siguiente: $NEXT_HTML_LINK
"""

prev_only = """
¡Bienvenido a la última parte de $SERIES_HTML_LINK!
¿Eres nuevo? Comienza con $FIRST_HTML_LINK para construir una base sólida.

Anterior: $PREV_HTML_LINK
"""

# Plantilla de respaldo.
default = "Este artículo es parte de la serie $SERIES_HTML_LINK."

# Conclusión.
[extra.series_outro_templates]
next_only = """
¡Gracias por leer! 🙌

Continúa tu viaje con $NEXT_HTML_LINK, donde $NEXT_DESCRIPTION
O revisa el esquema completo de la serie [$SERIES_TITLE]($SERIES_PERMALINK).
"""

middle = """
---
📝 Navegación de la serie

- Anterior: $PREV_HTML_LINK
- Siguiente: $NEXT_HTML_LINK
- [Resumen de la serie]($SERIES_PERMALINK)
"""

prev_only = """
🎉 ¡Felicidades! Has completado $SERIES_HTML_LINK.

¿Quieres repasar? Aquí comenzamos: $FIRST_HTML_LINK
O revisa lo que acabamos de ver en $PREV_HTML_LINK.
"""

# Respaldo.
default = """
---
Este artículo es la parte $SERIES_PAGE_INDEX de $SERIES_PAGES_NUMBER en $SERIES_HTML_LINK.
"""

Variables personalizadas

Las plantillas de series admiten variables personalizadas para incluir información adicional en toda tu serie. El proceso tiene dos pasos:

1. Primero, define tus marcadores en la configuración de tu serie (_index.md):

[extra]
series = true
series_template_placeholders = ["$POSITION", "$TOPIC", "$DIFFICULTY"]

2. Luego, en cada artículo de la serie, proporciona los valores para estos marcadores en series_template_variables:

[extra.series_template_variables]
position = "primero"
topic = "Variables y tipos"
difficulty = "Principiante"

Uso de variables personalizadas

Puedes usar tus variables personalizadas en cualquier plantilla, junto con las variables integradas:

[extra.series_intro_templates]
default = """
Este es el artículo $POSITION en $SERIES_HTML_LINK.
Tema de hoy: $TOPIC
Nivel de dificultad: $DIFFICULTY
"""

Ejemplo con variables personalizadas

# En la configuración de la serie.
[extra]
series = true
series_template_placeholders = ["$LEARNING_TIME", "$KEY_CONCEPTS"]

series_intro_templates.default = """
📚 Parte $SERIES_PAGE_INDEX de $SERIES_PAGES_NUMBER
⏱️ Tiempo estimado: $LEARNING_TIME
🔑 Conceptos clave: $KEY_CONCEPTS
"""

# En un artículo de la serie.
[extra.series_template_variables]
learning_time = "30 minutos"
key_concepts = "Funciones, manejo de errores, coincidencia de patrones"

Esto generará:

📚 Parte 2 de 5
⏱️ Tiempo estimado: 30 minutos
🔑 Conceptos clave: Funciones, manejo de errores, coincidencia de patrones