Skip to main content
A single wiki suits one team or one domain. When teams move independently, separate wikis keep their history and release cadence separate. The trade-off is that isolated wikis stop answering queries as one corpus. This guide shows how to compose an umbrella wiki from independent sub-wiki repositories, and how to manage those repositories as one multi-repo workspace with wspace. The umbrella wiki lists each sub-wiki under sources: in its wiki.yml, pins exact commits in wiki.lock, and keeps each sub-wiki as a named RDF graph. You can query the whole corpus at once, or trace a result back to its source repository. wspace keeps the repositories in sync with check, update, and worktree workflows.

​
Prerequisites

​
Reasons to split

Split when you want independent ownership, versioning, or release surfaces:
  • Each team owns its wiki history and merges its own changes.
  • A reference library (product docs, regulations, shared domain models) can be reused across multiple umbrellas.
  • Sub-wikis can publish or evolve on their own schedule.
Keep one wiki when the corpus is small or static, or when every page changes at the same pace. Splitting adds a composition layer; a single wiki is still simpler.

​
Layout

The umbrella repository owns wiki.yml with a sources: block that points at each sub-wiki repository. Each sub-wiki is its own Git repository. All repositories, umbrella and sub-wikis, are listed in one repos.json manifest so wspace manages them as a workspace:

​
Steps

1

Declare the repositories in the manifest

List the umbrella and each sub-wiki repository in repos.json, following the manifest schema:
Clone the missing repositories and confirm the workspace is healthy:
wspace check confirms every repository is present and clean. Keep the default branch current with the remote so later updates fast-forward cleanly:
See Workspace for the full command reference.
2

Compose the sub-wikis in wiki.yml

In the umbrella repository, declare each sub-wiki as an external source. Use a git URL with a #ref pin (branch, tag, or commit) so the composition is reproducible:
If a sub-wiki keeps its pages in a subdirectory, add path: <dir> to point at it. Each source name must be unique across the umbrella.Fetch the sources and pin the resolved commits:
This clones each repository into .wiki/sources/<name>/repo/, resolves the requested refs to commit SHAs, and writes wiki.lock:
Check wiki.lock into version control; it is the source of truth for which commit of each sub-wiki builds the corpus. If a source declares its own sources: block, wiki install fetches those transitive dependencies recursively; circular dependency chains raise an error.
For the full contract, see wiki install and External data sources (sources:). For the product framing, see Recursive Semantic Datasets.
3

Query the composed corpus with per-source provenance

Each sub-wiki stays a named RDF graph. List the graph boundaries:
This prints the root graph plus one graph per installed source, with the named graph URI, resolved commit, and dependency owner. Query the whole umbrella as one corpus:
Scope a query to one sub-wiki with a GRAPH clause:
Return the source graph with each result to trace provenance:
For the read-only boundary and graph URI derivation, see wiki graph.
4

Keep repositories and content in sync

Refresh repository baselines, then refresh installed sources:
wspace update fast-forwards clean default branches and skips dirty or feature-branch checkouts. wiki update re-fetches the installed sources, installs newly declared transitive sources, and reports orphaned ones. Remove sources you no longer want from the corpus (and their now-unused transitive dependencies):
5

Publish the umbrella

Sub-wiki edits happen in the sub-wiki repository, not in the umbrella’s .wiki/sources/ cache. Make changes there with the normal worktree workflow, then publish the umbrella:

​
Check for success

Run the integrity checks in the umbrella repository:
Then confirm each source resolves and its graph exists:

​
Next steps