Fontes

Uma fonte é uma pasta de Markdown: neste repositório ou noutro, no checkout atual ou em refs nomeadas. A lista sources é o único sítio onde são declaradas, e tudo o resto é gerado a partir dela.

sources: [
  { path: 'docs', slug: 'acme' },
  { repo: 'acme/api', path: 'docs', refs: ['main', 'v2.0.0', 'v1.4.0'] }
]

Dois repositórios e três refs: cinco coleções, os prefixos de URL que as servem, um seletor de versões, as regras de redirecionamento e as entradas do sitemap. Nada disso é escrito à mão. Cada campo está na referência de fontes.

#Como funciona

O Content v3 já faz a metade difícil. A fonte de uma coleção aceita um URL de repositório, um ramo ou tag e credenciais, e o Content descarrega-a e guarda-a em cache por hash — vários repositórios, repositórios privados e ler a partir de uma tag existem todos lá. O duxt não reimplementa nada disso.

O que o duxt acrescenta acontece ao carregar a configuração. content.config.ts é código executado e não um ficheiro de dados, por isso pode ler o app.config.ts do site e calcular as suas coleções a partir dessa lista — uma coleção por repositório × ref, cada uma com um cwd absoluto, um nome derivado do slug e o esquema de página de que o tema precisa. A mesma lista é resolvida uma segunda vez pela compilação, no manifesto: que coleção serve que prefixo de URL, que ref é a predefinida, de onde veio cada página. É esse manifesto que o tema lê, e é reescrito na configuração da aplicação como resolvedSources.

#Porque é feito assim

Declarar as coleções à mão não escala exatamente na direção em que a documentação cresce: três versões em catorze repositórios são quarenta e duas declarações, e cada lançamento edita as catorze. O atalho mantém a lista tão longa quanto o número de projetos.

O custo é que uma lista de fontes exprime menos do que uma coleção escrita à mão. É uma troca deliberada: quem precisar de algo que o atalho não consegue dizer escreve um content.config.ts próprio e assume por completo, porque o Content combina o ficheiro de cada camada, ganhando o posterior.

#O que daí resulta

Como uma fonte nomeia um repositório, uma ref e uma pasta, várias funcionalidades não precisam de configuração própria: «Editar esta página», a data da última alteração e a lista de quem contribuiu derivam todas dela. Ler o histórico de uma fonte remota custa um clone completo, por isso espera por history: true — um clone superficial reportaria o autor da ponta para cada ficheiro, o que são dados errados em vez de dados em falta.