Manage multiple wikis as a workspace

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

The wiki CLI, installed per the Wiki install guide.
The wspace CLI, installed per the Workspace install guide.
A repository for each sub-wiki, and one repository for the umbrella wiki.

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 workspace.json manifest so wspace manages them as a workspace:

workspace-root/
  wiki.yml          # umbrella: inputs + sources
  workspace.json     # wspace manifest
  repos/
    umbra-wiki/     # umbrella repository
    product-docs/   # sub-wiki repository
    team-brain/     # sub-wiki repository

Steps

Declare the repositories in the manifest

List the umbrella and each sub-wiki repository in workspace.json, following the manifest schema:

{
  "$schema": "https://wazootech.github.io/workspace-cli/schema.json",
  "workspaceRoot": ".",
  "repositoriesDirectory": "repos",
  "repositories": [
    {
      "name": "umbra-wiki",
      "url": "https://github.com/acme/umbra-wiki.git"
    },
    {
      "name": "product-docs",
      "url": "https://github.com/acme/product-docs.git"
    },
    {
      "name": "team-brain",
      "url": "https://github.com/acme/team-brain.git"
    }
  ]
}

Clone the missing repositories and confirm the workspace is healthy:

wspace install
wspace check

wspace check confirms every repository is present and clean. Keep the default branch current with the remote so later updates fast-forward cleanly:

wspace update

See Workspace for the full command reference.

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:

sources:
  - name: product-docs
    type: git
    url: https://github.com/acme/product-docs.git
    ref: v2.4.0
  - name: team-brain
    type: git
    url: https://github.com/acme/team-brain.git
    ref: main

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:

wiki install

This clones each repository into .wiki/sources/<name>/repo/, resolves the requested refs to commit SHAs, and writes wiki.lock:

wiki.lock: {
  "product-docs": "9f2a1c4",
  "team-brain": "3be7d90"
}

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.

Query the composed corpus with per-source provenance

Each sub-wiki stays a named RDF graph. List the graph boundaries:

wiki graph list

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:

SELECT ?s ?name WHERE {
  ?s schema:name ?name .
}

Scope a query to one sub-wiki with a GRAPH clause:

SELECT ?s ?name WHERE {
  GRAPH <https://example.org/wiki/graphs/source/product-docs> {
    ?s schema:name ?name .
  }
}

Return the source graph with each result to trace provenance:

SELECT ?g ?s ?name WHERE {
  GRAPH ?g {
    ?s schema:name ?name .
  }
}

For the read-only boundary and graph URI derivation, see wiki graph.

Keep repositories and content in sync

Refresh repository baselines, then refresh installed sources:

wspace update
wiki update

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):

wiki remove team-brain

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:

wiki build

Advanced: multiple workspaces

The steps above declare every repository in one flat manifest. Schema v4 keeps workspaces flat by design: each directory that contains a workspace.json is its own workspace. There is no nesting or delegation between manifests.

Nested workspaces were removed in schema v4

Earlier schema versions (v1-v3) supported nesting through a top-level workspaces: array and entry-level manifest and path fields. Schema v4 removed them:

A manifest that declares a top-level workspaces: key fails to load with a migration error: declare each child workspace’s repositories directly in the parent manifest instead.
Repository entries accept only name, url, and owner; the manifest and path entry fields are gone.
Manifests are JSON or JSONC only. The .yaml and .yml formats were removed, along with the fallback filenames wspace.json and repos.json.

Give a cluster its own workspace

To let a cluster of repositories change on its own cadence, give the cluster its own manifest. Any directory that holds a workspace.json is a workspace root; a checked-out repository can carry one at its root. Run wspace from that directory, or pass --manifest, to manage the cluster as its own workspace:

{
  "$schema": "https://wazootech.github.io/workspace-cli/schema.json",
  "schemaVersion": 4,
  "owner": "acme",
  "repositoriesDirectory": "repos",
  "repositories": ["umbra-wiki", "product-docs", "team-brain"]
}

Relative paths always anchor to the directory containing the manifest, so the umbrella repository’s checkout becomes the root of its sub-workspace. The parent workspace and the sub-workspace are independent: wspace commands run in the parent see only the parent’s repositories[], and commands run inside the umbrella checkout see only the sub-workspace’s list. A repository claimed by a sub-workspace must not also appear in the parent’s repositories[].

Workspaces organize Git repositories, while transitive sources: blocks compose RDF corpora. An umbrella can install another umbrella’s published corpus within one workspace, and separate workspaces can each hold umbrella wikis whose graphs never merge.

Check for success

Run the integrity checks in the umbrella repository:

wiki check --strict
wiki lint --strict

Then confirm each source resolves and its graph exists:

wiki graph list

Next steps

Wiki: validate, query, and publish semantic Markdown wikis
Workspace: manage multi-repository workspaces with wspace
External data sources (sources:): the composition reference
Recursive Semantic Datasets: the design behind named-graph provenance

Welcome

Platform

Skills

Ecosystem

Worlds

Guides

Console

Wazoo CLI

Integrations

Comparisons

Open source

Legal

Platform API

Worlds API

Manage multiple wikis as a workspace

Prerequisites

Reasons to split

Layout

Steps

Advanced: multiple workspaces

Nested workspaces were removed in schema v4

Give a cluster its own workspace

Check for success

Next steps

​Prerequisites

​Reasons to split

​Layout

​Steps

​Advanced: multiple workspaces

​Nested workspaces were removed in schema v4

​Give a cluster its own workspace

​Check for success

​Next steps

Prerequisites

Reasons to split

Layout

Steps

Advanced: multiple workspaces

Nested workspaces were removed in schema v4

Give a cluster its own workspace

Check for success

Next steps