Fontes

duxt.sources é uma lista de entradas de fonte; duxt.sourceOptions diz como se tornam URL. Ambas são lidas em tempo de compilação. O que geram, e porquê, está em Fontes.

#Uma entrada de fonte

Dois campos confundem-se facilmente e saem caros quando errados:

• repo descarrega, origin apenas liga. Nomear o teu próprio repositório em repo faz a compilação clonar o checkout onde já está.
• history custa um clone completo. O Content clona um repositório remoto com --depth 1, por isso o seu checkout tem um commit e cada ficheiro parece escrito por quem cortou a ponta — dados errados, não dados em falta. Ativá-lo completa o clone uma vez. Uma fonte lida do disco já é um checkout completo e é lida de qualquer maneira.

slug reclama um segmento. Normalmente uma fonte só recebe um quando a lista nomeia mais do que um repositório — tudo ou nada, para o site inteiro. Uma fonte que escreve o seu próprio slug é servida por baixo dele de qualquer maneira, e as que não escrevem nenhum ficam onde estão: é isso que deixa uma coisa viver em /demo ao lado de documentação que mantém a raiz.

#Refs

Um texto simples é um ramo. Uma tag tem de o dizer: o git guarda ramos e tags em espaços de nomes separados, e pedir uma tag sob refs/heads faz a compilação falhar com Could not find refs/heads/….

refs: [
  'main',                                     // um ramo
  { branch: 'next', status: 'upcoming' },     // o mesmo, com um ciclo de vida
  { tag: 'v2.0.0', label: 'v2' },             // uma tag
  'latest'                                    // a tag semver mais recente, resolvida na compilação
]

'latest' está reservado. Um ramo genuinamente chamado latest precisa da forma { branch }.

#Locales

Omitido, a fonte tem um idioma e uma coleção. Listado, cada entrada torna-se uma coleção própria.

locales: [
  'en-GB',                                              // o predefinido: o próprio docs/
  'de',                                                 // docs/de/
  { locale: 'fr', path: 'translations/fr' },            // noutro sítio deste repositório
  { locale: 'es', repo: 'acme/docs-es', path: 'docs' }  // outro repositório
]

Um texto é uma pasta dentro do path da fonte. A forma de objeto substitui path, repo e ref só para esse idioma — e é isso que permite a uma tradução viver num repositório próprio, com os seus responsáveis e o seu calendário de lançamentos.

O locale por omissão é a própria árvore em path e não ocupa pasta. Qual é vem de sourceOptions.defaultLocale, e tem de concordar com i18n.defaultLocale — a compilação falha se divergirem, porque content.config.ts resolve as coleções sem acesso à configuração do Nuxt.

Uma ref pode ter os seus próprios locales, sobrepondo-se aos da fonte tal como status faz. É essa a forma habitual: a versão atual está traduzida, as anteriores não.

refs: [
  { tag: 'v2.0.0' },                     // herda os locales da fonte
  { tag: 'v1.0.0', locales: ['en-GB'] }  // só o original
]

Nomeia uma pasta por idioma onde a região nada acrescente: docs/pt/ serve tanto pt-PT como pt-BR, porque uma página recai na sua língua base. A mesma regra que os ficheiros de locale da própria camada seguem.

#Estado

O que cada um custa a uma página está em URL e versões.

#Secções geradas

generated lista artefactos que não são Markdown e o tipo que lê cada um deles em páginas. O que é o mecanismo, e as duas políticas que um tipo responde, está em Secções geradas; os campos abaixo são os mesmos seja qual for o tipo que os lê.

path é um caminho e nunca um URL. Para uma fonte que o Content clona é relativo à raiz desse checkout, portanto o artefacto viaja com a versão a que pertence — uma regra em ambas as direções. Uma localização arbitrária permitiria buscar um artefacto de qualquer lado e reabriria a questão da rede em tempo de compilação que sources já fechou.

label é uma cadeia simples e não um texto traduzido, pela mesma razão pela qual a etiqueta de uma versão o é: um texto traduzido não é um URL estável.

options é opaco para tudo exceto o tipo que o lê — uma granularidade significa algo para um registo de alterações e nada para uma referência de API. Uma chave que o tipo não conhece faz a compilação falhar em vez de ser ignorada, porque uma opção mal escrita é um site que em silêncio não obtém o que configurou.

#Opções de fonte

#O manifesto resolvido

A compilação transforma a lista acima em duxt.resolvedSources, e é isso que o tema lê. useDuxtCollection() expõe-no; cada entrada transporta o nome da coleção, o prefix de URL, repo, version, isDefault, locale, isDefaultLocale, status, o repositório e a ref de onde vieram as páginas, e se o seu history foi lido.

O locale está deliberadamente ausente do prefix: o i18n já o coloca à frente do caminho, por isso todos os idiomas de uma fonte partilham um prefixo e só diferem pela coleção.