GBR SSG: Indexação e Árvore de Navegação (Sidebar)

Este documento descreve a estratégia de indexação de páginas e geração dinâmica do menu de navegação (Sidebar) no motor gbr_ssg.

1. Estratégia de Indexação em Duas Passagens

Para que todas as páginas geradas estaticamente possuam um menu lateral com links para as demais páginas, o processo de compilação da CLI deve ocorrer em *duas passagens*:

1. *Primeira Passagem (Extração de Metadados):* O motor varre todos os arquivos Markdown (.md) da pasta de entrada. Para cada arquivo, ele lê apenas o Frontmatter (título, categoria, ordem) e mapeia para a URL de destino (calculada a partir da pasta de saída relativa). Esses metadados são acumulados em um índice global chamado SiteIndex.

2. *Segunda Passagem (Renderização SSR com Índice):* Com o SiteIndex consolidado, o motor reprocessa cada arquivo Markdown, convertendo seu corpo em HTML e acoplando-o ao template de visualização do Lustre. O template recebe o SiteIndex e gera o componente de Sidebar (<aside>), ordenando as categorias e os links antes de gravar os arquivos HTML finais no disco.

2. Requisitos EARS

*Requisitos Ubíquos (Ubiquitous Requirements)* - *UBQ-01:* O motor deve ler os metadados title, category e order de todos os arquivos Markdown para construir o índice do site (SiteIndex). - *UBQ-02:* O motor deve gerar uma Sidebar dinâmica estruturada com a tag HTML5 <aside> em todas as páginas do site. - *UBQ-03:* A Sidebar deve conter links relativos corretos para todas as páginas indexadas, organizados hierarquicamente por categoria.

*Requisitos Orientados a Eventos (Event-Driven Requirements)* - *EVD-01:* Quando a Sidebar for renderizada, os itens dentro de cada categoria devem ser ordenados numericamente com base na propriedade order especificada no Frontmatter.

*Requisitos Orientados a Estado (State-Driven Requirements)* - *STD-01:* Se uma página possuir a propriedade order omitida em seu Frontmatter, o motor deve considerá-la com o valor de ordem padrão de fallback 9999 e ordená-la alfabeticamente pelo título em caso de empate. - *STD-02:* Se a propriedade category for omitida no Frontmatter, o motor deve inferir a categoria com base no nome do diretório pai onde o arquivo Markdown está localizado. Se o arquivo estiver na raiz, deve ser agrupado na categoria padrão "Geral".

*Requisitos de Comportamento Indesejado (Unwanted Behavior Requirements)* - *UNW-01:* Se a propriedade order no Frontmatter contiver um valor não-inteiro (malformado), o motor deve reportar um aviso de conversão de tipo no console, assumir o valor de fallback 9999 e continuar o build.

3. Árvore de Navegação em Gleam (AST de Navegação)

A estrutura de dados a ser adotada no core para modelagem do índice e agrupamento da árvore de navegação é a seguinte:

/// Representa metadados essenciais de uma página para indexação.
pub type PageMetadata {
  PageMetadata(
    title: String,
    path: String,
    category: String,
    order: Int,
  )
}

/// O índice geral acumulado do site.
pub type SiteIndex {
  SiteIndex(pages: List(PageMetadata))
}

/// Representa a árvore de navegação final (Sidebar) gerada a partir do índice.
/// A tupla contém o nome da Categoria e a lista de páginas correspondentes,
/// já ordenadas.
pub type NavigationTree = List(#(String, List(PageMetadata)))