Saltar para o conteúdo
duxt

Vários repositórios

Servir a documentação de vários projetos a partir de um só site.

Um site, muitos projetos. Cada repositório de origem contém apenas Markdown — sem Nuxt, sem package.json, sem dependências — o que é a única disposição viável para um projeto em Go, PHP ou Rust.

Passos

  1. Nomeia cada repositório como uma fonte. Um segmento de repositório aparece em todos os URL assim que há mais do que um, por isso dá a cada um um slug que estejas disposto a manter: faz parte do URL.
    sources: [
  { path: 'docs', slug: 'acme', origin: { repo: 'acme/site', ref: 'main' } },
  { repo: 'acme/api', path: 'docs' },
  { repo: 'acme/cli', path: 'docs' }
]
  2. Usa origin, não repo, para este repositório. repo é o que faz o Content descarregar uma fonte, por isso nomear o teu aí faria a compilação clonar o checkout onde já está. origin diz apenas onde vivem as páginas, para a ligação «Editar esta página».
  3. Autentica os privados. O Content lê um token do auth da coleção; nada disso é específico do duxt.
  4. Escreve as tuas próprias sections. A navegação que a camada traz assume uma única fonte sem prefixo. Com um segmento de repositório em cada caminho, as suas entradas deixam de resolver: nomeia as secções tu mesmo, apontando para /acme/getting-started em vez de /getting-started.
  5. Compila uma vez e lê as mensagens. Uma coleção vazia faz a compilação falhar, e é a falha que esta montagem produz mais vezes: um path que não existe no outro repositório parece exatamente um repositório sem documentação.

O que recebes de graça

A pesquisa consulta cada coleção selecionada em separado, mantém a ordenação própria de cada uma e intercala as mesmas posições, começando pela fonte atual do leitor. Pesquisa a versão em leitura ou a predefinida dessa fonte, uma por repositório, para que uma página não apareça uma vez por versão. _partials/ de qualquer fonte alimenta uma coleção partilhada, por isso uma nota de instalação escreve-se uma vez e inclui-se nos três projetos.

Lista de verificação

  • Cada fonte tem um slug que te agrada ter no URL
  • Este repositório usa origin, não repo
  • As sections apontam para caminhos que incluem o segmento de repositório
  • A compilação não reporta nenhuma coleção vazia
  • Pesquisar a partir de um repositório encontra uma página noutro
Esta página foi útil?