Plugin + Liquid: funcionamiento del indice de sitio

Objetivo

Reducir costo de render en includes que antes hacian busquedas repetidas sobre site.pages, site.posts y colecciones.

Flujo general

1. El plugin /_plugins/build_site_index.rb corre en post_read.
2. Construye site.data.site_index con lookups precomputados.
3. navigation, pagination, topics-page y tags-page consumen siempre ese indice.
4. Solo cards mantiene doble camino controlado por use_site_index_cards.

Flags de control

En /_config.yml:

• use_site_index_cards: activa/desactiva el indice especifico de cards.

En páginas con layout: series:

• show_project_refs_on_cards: por defecto false; usar true para mostrar, en las tarjetas del índice, la lista de proyectos referenciados por project_ref.

Estructura clave del indice

site.data.site_index incluye:

• meta: fecha y contadores.
• config: flags efectivos.
• lookups:
  • pages_by_translation_key_lang
  • docs_by_translation_key_lang
  • pages_by_url
  • docs_by_url
  • all_docs_by_url
  • index_pages_by_collection_lang
• pagination:
  • by_collection_lang
  • prev_next_by_url
• taxonomies:
  • topics_by_lang
  • tags_by_lang
• relations:
  • project_ref_reverse
  • project_series_reverse
• cards (si esta habilitado)

Regla de idiomas en taxonomias

Para mantener compatibilidad con las paginas de topics/tags:

• lang: nil se distribuye a todos los idiomas.
• En topics, lang: "" se trata como es.
• En tags, lang: "" se omite (comportamiento legacy).

Consumo desde Liquid

Includes migrados a index-only:

• /_includes/navigation.html
• /_includes/pagination.html
• /_includes/topics-page.html
• /_includes/tags-page.html
• /_includes/cards.html (unico include con fallback, guardado por use_site_index_cards)

Patron comun:

1. Resolver current_lang con fallback a es.
2. Leer datos precomputados por URL/idioma.
3. En cards, usar indice solo cuando use_site_index_cards esta en true.

Riesgos y mitigacion

• Riesgo: desalineacion de idioma o labels en taxonomias.
  • Mitigacion: validacion con build profile y pruebas por idioma.
• Riesgo: cards puede degradar tiempo de build.
  • Mitigacion: use_site_index_cards: false por defecto.
• Riesgo: cambios de estructura en plugin rompen includes.
  • Mitigacion: usar claves estables en site_index y validar en CI.

Validacion recomendada

Build base recomendada:

• bundle exec jekyll build --profile

Build alternativa (solo para analizar cards index):

• en /_config.yml, cambiar temporalmente use_site_index_cards a true
• ejecutar bundle exec jekyll build --profile