Skip to content
duxt

Several repositories

Serve the documentation of several projects from one site.

One site, many projects. Each source repository holds nothing but Markdown — no Nuxt, no package.json, no dependencies — which is the only workable arrangement for a Go, PHP or Rust project.

Steps

  1. Name each repository as a source. A repository segment appears in every URL as soon as there is more than one, so give each a slug you are willing to keep — it is part of the URL.
    sources: [
  { path: 'docs', slug: 'acme', origin: { repo: 'acme/site', ref: 'main' } },
  { repo: 'acme/api', path: 'docs' },
  { repo: 'acme/cli', path: 'docs' }
]
  2. Use origin, not repo, for this repository. repo is what makes Content download a source, so naming your own there has the build clone the checkout it is already standing in. origin only says where the pages live, for the "Edit this page" link.
  3. Authenticate the private ones. Content reads a token from the collection's auth; nothing about it is duxt-specific.
  4. Write your own sections. The navigation the layer ships assumes a single unprefixed source. With a repository segment in every path, its entries no longer resolve, so name the sections yourself — pointing at /acme/getting-started rather than /getting-started.
  5. Build once and read the messages. An empty collection fails the build, and it is the failure this setup produces most: a path that does not exist in the other repository looks exactly like a repository with no documentation.

What you get for free

Search queries every selected collection separately, keeps the ranking from each collection and interleaves equal result positions, with the reader's current source first. It searches the version they are reading, or that source's default, one per repository, so a page never appears once per version. _partials/ from any source feeds one shared collection, so an install note can be written once and included in all three projects.

Checklist

  • Every source has a slug you are content to have in the URL
  • This repository uses origin, not repo
  • sections point at paths that include the repository segment
  • The build reports no empty collection
  • Search from one repository finds a page in another
Was this page helpful?