`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](/concepts/sources). 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 | Campo | Tipo | Notas | | :-------- | :----------------------- | :---------------------------------------------------------------- | | `path` | `string` | Pasta com o Markdown, relativa à raiz do repositório | | `repo` | `string` | `owner/name` ou um URL git. **Omitido significa o checkout local** | | `refs` | lista de refs | Refs a publicar como versões; exigem um `repo` explícito | | `releases` | `{ select, prereleases? }` | Descobrir tags de versão para publicação — ver abaixo | | `tagComponent` | `string` | Publicar apenas as tags `@vX.Y.Z` de um pacote — ver [Tags por componente](#tags-por-componente) | | `version` | `string` | A versão que esta fonte representa por si própria | | `label` | texto | Mostrado no seletor e usado no URL; por omissão, a ref | | `name` | texto | Como esta fonte **se chama** onde o site a nomeia. Apenas visualização — ver abaixo | | `slug` | `string` | O segmento de URL desta fonte. **Declará-lo é reclamá-lo** — ver abaixo | | `status` | estado | Ciclo de vida de cada versão que esta entrada publica | | `statusDefaults` | `{ latest?, branch?, tag? }` | Ciclo de vida predefinido por tipo de ref | | `origin` | `{ repo, ref?, path? }` | Onde vivem as páginas lidas do disco, para ligar de volta | | `history` | `boolean` | Ler o histórico git desta fonte | | `content` | `boolean` | `false` se a fonte apenas transportar material gerado | | `exclude` | `{ drafts?, partials? }` | Globs por fonte para rascunhos e parciais | | `flavor` | `'tfplugindocs'` | Interpretar a árvore Markdown como um dialeto suportado | | `locales` | lista de locales | Idiomas em que esta fonte existe — ver abaixo | | `generated` | lista de secções | Artefactos publicados como páginas ao lado do Markdown — ver abaixo | 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. ```ts 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](/guides/publish-terraform-provider-docs). ## 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/…`. ```ts 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. ```ts { repo: 'acme/sdk', path: 'docs', releases: { select: 'minor' } } ``` | `select` | Publica | | :-------- | :----------------------------------------------- | | `'all'` | cada lançamento | | `'minor'` | o lançamento mais recente de cada linha minor | | `'major'` | o lançamento mais recente de cada linha major | 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. ```ts { 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 `@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: ```ts { 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. ```ts 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. ```ts 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. ```ts statusDefaults: { latest: 'current', branch: 'upcoming', tag: 'deprecated' } ``` | Valor | Significa | | :----------- | :---------------------------------------------------- | | `upcoming` | Ainda não lançada — pode ainda mudar | | `current` | A documentação a ler | | `maintained` | Mais antiga, ainda suportada | | `deprecated` | Mais antiga, e o leitor deve atualizar | | `eol` | Morta — avisada, e fora do sitemap | O que cada um custa a uma página está em [URL e versões](/concepts/urls-and-versions). ## 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](/concepts/generated-sections); os campos abaixo são os mesmos seja qual for o tipo que os lê. | Campo | Tipo | Notas | | :----------- | :----------------------- | :------------------------------------------------------------ | | `type` | `string` | A chave de registo do tipo — `changelog`, `openapi`, `bruno`, o teu | | `path` | `string` | O artefacto, relativo à raiz própria da fonte | | `label` | `string` | A entrada da barra e — slugificada — o segmento de URL | | `slug` | `string` | Substitui o segmento que a etiqueta produziria | | `options` | objeto | Os botões que esse tipo oferece; cada tipo valida os seus | | `versions` | lista de versões | As versões deste artefacto — ver abaixo | | `locales` | `Record` | Um artefacto por idioma, lido apenas por um tipo `per-locale` | | `navigation` | colocação | `'sections'` (predefinição), `'navigation'` ou `false` | | `icon` | `string` | Recai no ícone próprio do tipo | **`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. ```ts [app/app.config.ts] generated: [ { type: 'openapi', label: 'API', path: 'openapi/v2.yaml', versions: [ { version: 'v2', path: 'openapi/v2.yaml' }, { version: 'v1', path: 'openapi/v1.yaml', status: 'deprecated' } ] } ] ``` | Campo | Notas | | :-------- | :---------------------------------------------------------------- | | `version` | Mostrada no seletor e usada no URL | | `path` | O artefacto desta versão; por omissão, o caminho da declaração | | `locales` | Artefactos por locale para esta versão | | `status` | Ciclo de vida — `deprecated`, `eol`, `upcoming` | | `default` | Servida sem segmento de versão; primeira entrada por omissão | 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 | Campo | Por omissão | O que faz | | :-------------- | :------------------ | :---------------------------------------------------------- | | `showRepo` | desligado | Força um segmento de repositório com um só repositório | | `showVersion` | desligado | Força um segmento de versão com uma só versão | | `defaultRef` | a primeira ref | A ref servida sem prefixo de versão | | `defaultLocale` | o primeiro locale | O locale servido a partir do próprio `path`, sem pasta | ## 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.