Zum Inhalt springen
duxt

Mehrere Repositories

Die Dokumentation mehrerer Projekte von einer Seite ausliefern.

Eine Seite, viele Projekte. Jedes Quell-Repository enthält nichts als Markdown — kein Nuxt, keine package.json, keine Abhängigkeiten — was die einzige praktikable Anordnung für ein Go-, PHP- oder Rust-Projekt ist.

Schritte

  1. Benenne jedes Repository als Quelle. Ein Repository-Segment erscheint in jeder URL, sobald es mehr als eines gibt — gib also jedem einen slug, den du zu behalten bereit bist: Er ist Teil der URL.
    sources: [
  { path: 'docs', slug: 'acme', origin: { repo: 'acme/site', ref: 'main' } },
  { repo: 'acme/api', path: 'docs' },
  { repo: 'acme/cli', path: 'docs' }
]
  2. Nimm origin, nicht repo, für dieses Repository. repo ist das, was Content eine Quelle herunterladen lässt — das eigene dort zu nennen, ließe den Build den Checkout klonen, in dem er bereits steht. origin sagt nur, wo die Seiten liegen, für den Link „Diese Seite bearbeiten“.
  3. Authentifiziere die privaten. Content liest ein Token aus dem auth der Collection; nichts daran ist duxt-spezifisch.
  4. Schreibe deine eigenen sections. Die Navigation, die die Ebene mitbringt, nimmt eine einzelne Quelle ohne Präfix an. Mit einem Repository-Segment in jedem Pfad lösen ihre Einträge nicht mehr auf — benenne die Sektionen also selbst und zeige auf /acme/getting-started statt auf /getting-started.
  5. Baue einmal und lies die Meldungen. Eine leere Collection lässt den Build scheitern, und das ist der Fehlschlag, den dieses Setup am häufigsten erzeugt: Ein path, den es im anderen Repository nicht gibt, sieht genauso aus wie ein Repository ohne Dokumentation.

Was du kostenlos bekommst

Die Suche erstreckt sich über jede Quelle und bewertet die Treffer gemeinsam, wobei die Quelle, in der der Leser gerade ist, zuerst kommt — die Version, die er liest, oder deren Standard, eine je Repository, damit eine Seite nie einmal pro Version erscheint. _partials/ aus jeder Quelle speist eine gemeinsame Collection, ein Installationshinweis kann also einmal geschrieben und in allen drei Projekten eingebunden werden.

Checkliste

  • Jede Quelle hat einen slug, den du in der URL haben willst
  • Dieses Repository nutzt origin, nicht repo
  • sections zeigen auf Pfade, die das Repository-Segment enthalten
  • Der Build meldet keine leere Collection
  • Die Suche aus einem Repository findet eine Seite in einem anderen
War diese Seite hilfreich?