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.

Os refs exigem um repo explícito, mesmo para publicar outro ref deste repositório. Sem repo, a fonte lê o checkout local atual e rejeita refs (incluindo latest) e substituições locais de ref por idioma. origin.repo e origin.ref fornecem apenas ligações de proveniência; não selecionam conteúdo. Um idioma com o seu próprio repo explícito pode escolher o seu próprio ref. Para versões locais, use version em fontes com pastas distintas ou as versions por ficheiro de uma secção gerada.

#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á.
• origin.path é a pasta na forja. Defina-o quando a pasta no disco é uma cópia — conteúdo copiado para um contexto de build, um checkout vizinho lido através de ../ — para que «Edit this page» abra docs/… e não o caminho da cópia. As pastas de idioma são mapeadas através do path da fonte, por isso têm de estar dentro dele.
• 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.

name é um nome; label e slug são endereços. O diálogo de pesquisa legenda cada resultado com a fonte de onde veio e, antes desta chave, só o conseguia ler do URL — uma documentação servida na raiz anunciava-se como /, e uma fonte cujo segmento é uma abreviatura, como tf. name é apenas visualização: não chega a nenhuma coleção, prefixo, versão nem ao ranking — é precisamente por isso que pode ser prosa e pode ser traduzido.

sources: [
  // Um registo de locales, porque o nome é um substantivo que se traduz.
  {
    repo: 'acme/docs',
    path: 'docs',
    name: { 'en-GB': 'Handbook', de: 'Handbuch', fr: 'Manuel' }
  },
  // Um literal simples, porque um nome de produto é a mesma palavra em toda a parte.
  { repo: 'acme/terraform-provider-acme', path: 'docs', slug: 'tf', name: 'Terraform Provider' }
]

Por declarar, o nome recai sobre o próprio segmento da fonte (demo → Demo) e depois sobre duxt.title, que num site sem título é a própria etiqueta localizada Documentação. Vale a pena declará-lo sempre que o segmento seja uma abreviatura. Duas fontes diferentes que acabariam com um mesmo nome são distinguidas automaticamente pelo seu repositório ou pela sua pasta.

#Conteúdo, exclusões e dialetos de fonte

content: false não publica páginas Markdown comuns da fonte, mas mantém ativas as suas declarações generated. exclude.drafts e exclude.partials substituem os globs dessa fonte quando um repositório segue outras convenções.

flavor: 'tfplugindocs' interpreta as pastas, títulos e categorias de uma árvore Markdown produzida pelo tfplugindocs. As páginas continuam a ser páginas Content comuns para pesquisa, versões, locales e leitores automáticos. Ver Publicar documentação de um provider Terraform.

#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 }.

#Releases

releases descobre tags em vez de manter um histórico longo na configuração. A descoberta é opt-in e diz sempre o que seleciona: não existe um “todos os lançamentos” implícito, porque os URLs que permanecem acessíveis são uma decisão do site.

{
  repo: 'acme/sdk',
  path: 'docs',
  releases: { select: 'minor' }
}

As pré-versões ficam de fora salvo se prereleases: true as incluir. A versão selecionada mais recente é a predefinida; uma ref com default: true ou sourceOptions.defaultRef continua a prevalecer.

O ciclo de vida não muda: o estado da fonte ou statusDefaults.tag aplica-se a cada tag descoberta. Nada é inferido da idade de um lançamento.

refs continua disponível ao lado de releases. Uma entrada para uma tag descoberta substitui a etiqueta, o estado, o valor predefinido e os locales; qualquer outra é publicada ao lado.

{
  repo: 'acme/sdk',
  releases: { select: 'major' },
  refs: [
    { tag: 'v1.4.2', label: 'v1', status: 'deprecated' },
    { branch: 'main', status: 'upcoming' }
  ]
}

Uma seleção sem tag correspondente para a build e identifica a fonte e a seleção. Um repositório ilegível é comunicado separadamente como erro de Git. A mesma distinção aplica-se a latest.

#Tags por componente

Um monorepo que publica vários pacotes separadamente marca cada um pelo seu componente — o release-please escreve duxt@v0.4.0 ao lado de duxt-typesense@v0.1.0. Ambas as formas são versões: latest, releases e a ordem do seletor leem <name>@vX.Y.Z tal como vX.Y.Z, e a etiqueta e o segmento de URL mostram apenas a versão — v0.4.0, nunca duxt@v0.4.0. A ref guarda a tag completa, porque é o nome que o git conhece.

Quando o repositório marca mais do que um pacote, “a tag mais recente” não quer dizer nada até dizer de qual. tagComponent nomeia o pacote:

{
  repo: 'kirchDev/duxt',
  path: 'docs',
  tagComponent: 'duxt',
  refs: [{ tag: 'latest', default: true }]   // duxt@v…, nunca duxt-typesense@v…
}

As tags vX.Y.Z simples continuam a contar: são os lançamentos do pacote anteriores às tags por componente, e descartá-las despublicaria cada um. As tags de outro componente nunca contam. Sem tagComponent, qualquer tag que se leia como versão é candidata, com ou sem prefixo.

#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

statusDefaults define um ciclo de vida por tipo de ref quando a própria ref não o indica: latest para a tag escolhida pela entrada reservada, branch para branches e tag para tags explícitas ou descobertas. O estado explícito de uma ref prevalece; o estado da fonte é o fallback comum.

statusDefaults: {
  latest: 'current',
  branch: 'upcoming',
  tag: 'deprecated'
}

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.

#Uma secção com versões próprias

Uma versão é normalmente um checkout: refs na fonte publica cada secção uma vez por ref. Uma API, porém, costuma guardar openapi/v1.yaml ao lado de openapi/v2.yaml no mesmo repositório e ser versionada por ficheiro. Sem versions, seriam duas secções independentes e duas entradas de navegação.

generated: [
  {
    type: 'openapi',
    label: 'API',
    path: 'openapi/v2.yaml',
    versions: [
      { version: 'v2', path: 'openapi/v2.yaml' },
      { version: 'v1', path: 'openapi/v1.yaml', status: 'deprecated' }
    ]
  }
]

A versão predefinida é servida em /api e as restantes sob o seu segmento, como /v1/api. O seletor oferece-as como as refs de uma fonte, com o aviso, noindex e canonical de uma versão que não é a atual.

São declaradas juntas em vez de como duas fontes de propósito: só variantes produzidas por uma declaração são oferecidas como versões umas das outras. Uma fonte por versão da API publicaria ainda duas vezes a árvore de documentação.

Nunca as uses junto de refs na mesma fonte. Ambas as formas reclamam o mesmo segmento do URL e a compilação rejeita a combinação. Um tipo global também as rejeita porque publica uma única história num URL neutro. Um changelog não é global: é publicado por versão e pode levar versions como uma referência de API.

#Qual versão é qual

Três coisas se chamam versão à volta de uma página de referência, mas só duas pertencem ao duxt:

• A versão no URL e no seletor é uma ref ou um valor version declarado acima. O distintivo mostra que variante estás a ler.
• duxt.version é a cadeia própria do site. Só aparece no distintivo quando não há nada entre que alternar.
• info.version de um documento OpenAPI é a afirmação do documento sobre a API descrita. Surge como Versão da API na página de referência, nunca no distintivo do seletor.

Os números são muitas vezes semelhantes, mas continuam a ser factos diferentes; o duxt não deriva nenhum do outro.

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, name, 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.

#Mídia da documentação

Imagens geradas pertencem a docs/_assets/. As referências são relativas ao arquivo Markdown: docs/1.guides/1.demo.md usa ../_assets/demo.gif. O prefixo /_assets/ indica a raiz da documentação da fonte. A mesma regra se aplica ao atributo de imagem dark.

duxt publica automaticamente imagens PNG, JPEG, GIF, SVG, WebP, AVIF, APNG e ICO, inclusive fontes remotas no ref selecionado. As URLs separam repositório, raiz da documentação e ref; preservam os links de páginas e o provedor de imagens. _assets/ não vira seção nem página. Tapes, scripts, Dockerfiles e outras fontes de captura não são publicados.

Imagens sem idioma ficam em _assets/ compartilhado. Uma página em docs/de/ pode usar ../_assets/demo.gif; uma variante alemã produzida explicitamente em docs/de/_assets/ usa _assets/demo.gif. As imagens vêm do repositório e ref da página. Um repositório de tradução compartilha imagens dentro de seu checkout, sem buscar mídia de outro repositório implicitamente. Traduza textos alternativos e legendas com a página.