GBR SSG: Indexação e Árvore de Navegação com TOML Frontmatter

Este documento detalha a transição do Frontmatter para o formato TOML e o uso da biblioteca oficial tom para gerar a árvore de navegação lateral (Sidebar) do SSG.

1. Estratégia de Parse do TOML Frontmatter

A extração do Frontmatter ocorrerá isolando as linhas de texto entre os delimitadores +++ ou --- no topo dos arquivos Markdown.

• *Delimitadores Aceitos:* +++ (padrão TOML) ou --- (compatibilidade histórica com YAML).
• **Processamento via tom:** O bloco extraído de texto em formato TOML será repassado para a biblioteca tom (tom.parse).
• *Decodificação de Campos:* - title (String): Título amigável da página (obrigatório). Se ausente, o SSG infere a partir do nome do arquivo (ex: meu-post vira Meu post). - description (String): Descrição curta da página para SEO (opcional, padrão ""). - category (String): Categoria de agrupamento (opcional). Se ausente, infere a partir da pasta pai ou assume "Geral". - order (Int): Inteiro definindo a ordem de exibição no menu lateral (opcional, padrão 9999).

2. Requisitos EARS

*Requisitos Ubíquos (Ubiquitous Requirements)* - *UBQ-01:* O motor deve identificar e extrair o conteúdo contido entre delimitadores +++ ou --- no topo dos arquivos Markdown. - *UBQ-02:* O motor deve utilizar a biblioteca tom para realizar o parse da string extraída em uma árvore AST de TOML. - *UBQ-03:* O motor deve decodificar os tipos de dados TOML correspondentes às chaves title, description, category e order. - *UBQ-04:* A Sidebar deve exibir os links organizados pelas categorias resolvidas.

*Requisitos Orientados a Eventos (Event-Driven Requirements)* - *EVD-01:* Quando a navegação for construída, os links dentro de uma mesma categoria devem ser ordenados numericamente de forma ascendente com base na propriedade order. - *EVD-02:* Em caso de empate na ordem numérica (ou uso do fallback 9999), o motor deve ordenar os itens alfabeticamente pelo título.

*Requisitos Orientados a Estado (State-Driven Requirements)* - *STD-01:* Enquanto o SiteIndex estiver sendo consolidado, o motor deve calcular a URL/caminho relativo do arquivo HTML estático final de cada página para alimentar a Sidebar.

*Requisitos de Comportamento Indesejado (Unwanted Behavior Requirements)* - *UNW-01:* Se a string TOML contida no Frontmatter for inválida, o parser deve retornar um erro, e o build daquela página específica deve ser abortado (UNW-01 do passo 1) com um log explicativo no console indicando a falha de sintaxe TOML. - *UNW-02:* Se a chave order estiver presente mas seu valor no TOML não for um número inteiro, o motor deve ignorar o valor inválido, emitir um aviso no console e atribuir o valor padrão de fallback 9999 para permitir que o build da página continue.

3. Estruturas de Dados Propostas (Gleam)

Mapeamento no core (gbr_ssg_core):

/// Metadados estruturados extraídos de uma página.
pub type PageMetadata {
  PageMetadata(
    title: String,
    description: String,
    path: String,
    category: String,
    order: Int,
  )
}

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

/// Árvore ordenada e agrupada por categoria para a Sidebar.
pub type NavigationTree = List(#(String, List(PageMetadata)))