Saltar al contenido
duxt

Varios repositorios

Servir la documentación de varios proyectos desde un solo sitio.

Un sitio, muchos proyectos. Cada repositorio de origen no contiene más que Markdown — sin Nuxt, sin package.json, sin dependencias — que es la única disposición viable para un proyecto en Go, PHP o Rust.

Pasos

  1. Nombra cada repositorio como una fuente. Un segmento de repositorio aparece en cada URL en cuanto hay más de uno, así que dale a cada uno un slug que estés dispuesto a conservar: forma parte de la 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, no repo, para este repositorio. repo es lo que hace que Content descargue una fuente, así que nombrar el tuyo ahí haría que la compilación clonara el checkout en el que ya está. origin solo dice dónde viven las páginas, para el enlace «Editar esta página».
  3. Autentica los privados. Content lee un token del auth de la colección; nada de eso es específico de duxt.
  4. Escribe tus propias sections. La navegación que trae la capa da por supuesta una única fuente sin prefijo. Con un segmento de repositorio en cada ruta, sus entradas dejan de resolver: nombra las secciones tú mismo, apuntando a /acme/getting-started en lugar de a /getting-started.
  5. Compila una vez y lee los mensajes. Una colección vacía hace fallar la compilación, y es el fallo que este montaje produce más a menudo: un path que no existe en el otro repositorio se ve exactamente igual que un repositorio sin documentación.

Lo que obtienes gratis

La búsqueda abarca todas las fuentes y ordena los resultados en conjunto, con la fuente en la que está el lector primero — la versión que está leyendo, o su predeterminada, una por repositorio, para que una página nunca aparezca una vez por versión. _partials/ de cualquier fuente alimenta una colección compartida, así que una nota de instalación se escribe una vez y se incluye en los tres proyectos.

Lista de comprobación

  • Cada fuente tiene un slug que te conviene tener en la URL
  • Este repositorio usa origin, no repo
  • Las sections apuntan a rutas que incluyen el segmento de repositorio
  • La compilación no informa de ninguna colección vacía
  • Buscar desde un repositorio encuentra una página de otro
¿Le ha resultado útil esta página?