Running a Federated Docs Site: Many nbdev Repos, One Website

How a dozen independent nbdev + Quarto repos publish to separate GitHub Pages sites yet read as one - the shared-chrome trick behind bthek1.github.io.
Author

Benedict Thekkel

Published

July 6, 2026

bthek1.github.io looks like one website. It isn’t. It’s ~18 independent nbdev + Quarto sites, each published to its own GitHub Pages URL, stitched into the illusion of one site by identical chrome. Here’s the trick.

The problem

Each topic is its own nbdev repo (its own package, its own docs build). I did not want one giant monolithic site - repos stay independent, buildable, and publishable on their own. But I did want them to feel like one place. There is no combined build; the unification is pure convention.

The architecture

flowchart TB
  ROOT[Knowledge mono-repo] --> QY[_quarto.yml canonical: navbar/theme/footer]
  ROOT --> CP[just copy_quarto]
  CP --> S1[Sub: DeepLearning/nbs]
  CP --> S2[Sub: WEB_doc/nbs]
  CP --> S3[Sub: ...15 more]
  S1 --> P1[Pages: /DeepLearning]
  S2 --> P2[Pages: /WEB_doc]
  S3 --> P3[Pages: /...]
  P1 -. shared navbar links .- P2
  P2 -. shared navbar links .- P3

Three pieces make it work

Piece Source Role
Canonical _quarto.yml mono-repo root The one true navbar, theme, footer, search
just copy_quarto mono-repo justfile Pushes _quarto.yml + logos into every submodule’s nbs/
Per-site nbdev.yml each submodule Site title / URL / repo, merged via metadata-files

The navbar hrefs are absolute URLs across the separate Pages sites. Click an item and you cross from one site to another - but since every site carries the same copied navbar, theme, and logo, it reads as one continuous site.

The federated sites

A slice of what’s stitched together (each is its own repo + Pages site):

Category Site
Deep Learning https://bthek1.github.io/DeepLearning
Web / backend https://bthek1.github.io/Back_End
Web / infra https://bthek1.github.io/WEB_doc
Python libs https://bthek1.github.io/MLtools
Tools https://bthek1.github.io/Software_Tools
Hardware https://bthek1.github.io/Hardware_Tools
Time series https://bthek1.github.io/TimeSeries_ML
Finances https://bthek1.github.io/Finances

The publish flow

flowchart LR
  E[Edit root _quarto.yml] --> CP[just copy_quarto]
  CP --> N[nbdev_docs per submodule]
  N --> GP[GitHub Pages x N]
  GP --> ONE[Looks like one site]

Change the nav in one place, copy_quarto, rebuild, and every site updates in lockstep.

Trade-offs

Win Cost
Repos stay independent + small N sites to rebuild on a chrome change
Any repo builds/publishes alone Cross-site search is per-site
No monolith to break Navbar URLs are absolute, must be kept in sync

For a personal knowledge base that grows one topic at a time, the independence is worth the rebuild cost. The whole mechanism lives in the mono-repo’s root _quarto.yml and justfile.

Back to top