Split configuration with $ref

Use $ref to move part or all of docs.json into another JSON file. Shiso resolves references before it validates or builds the site, so the resolved configuration behaves like one docs.json file. References apply to docs.json only; shiso.config.ts is a regular TypeScript module and can use import instead.

Reference the whole configuration#

Keep the schema declaration in docs.json, then reference a configuration file with a relative path:

docs.json:

{
  "$schema": "./node_modules/@umami/shiso/docs.schema.json",
  "$ref": "./config/site.json"
}

config/site.json:

{
  "name": "Acme docs",
  "navigation": {
    "pages": ["index", "installation"]
  }
}

Reference paths must:

• Be relative paths to .json files.
• Stay inside the project root, including after symbolic links are resolved.
• Be relative to the JSON file containing the $ref, not always to docs.json.

URLs, absolute paths, and paths that escape the project are rejected.

Reference one section#

You can use $ref anywhere Shiso accepts a configuration object. This is useful for separating large navigation trees from site-wide settings:

docs.json:

{
  "$schema": "./node_modules/@umami/shiso/docs.schema.json",
  "name": "Acme docs",
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}

config/navigation.json:

{
  "groups": [
    {
      "group": "Getting started",
      "pages": ["index", "installation"]
    }
  ]
}

References also work for objects inside arrays. For example, a navigation group can live in its own file:

config/navigation.json:

{
  "groups": [
    { "$ref": "./groups/getting-started.json" },
    { "$ref": "./groups/api-reference.json" }
  ]
}

Because these references appear in config/navigation.json, both paths are resolved from the config folder.

Override referenced values#

Properties beside $ref override properties from a referenced object:

docs.json:

{
  "$schema": "./node_modules/@umami/shiso/docs.schema.json",
  "$ref": "./config/site.json",
  "name": "Acme API docs"
}

If config/site.json sets name to "Acme docs", the resolved name is "Acme API docs".

Overrides are shallow. Replacing an object property replaces that entire object rather than merging each of its properties. To override a nested value, put the $ref and override at that nested level:

{
  "navigation": {
    "$ref": "./config/navigation.json",
    "anchors": [
      { "anchor": "Status", "href": "https://status.example.com" }
    ]
  }
}

Reference arrays and primitive values#

A referenced file can contain any JSON value. For example, an array reference is useful for a long page list:

docs.json:

{
  "$schema": "./node_modules/@umami/shiso/docs.schema.json",
  "navigation": {
    "pages": { "$ref": "./config/pages.json" }
  }
}

config/pages.json:

["index", "installation", "quickstart"]

Primitive values work the same way:

docs.json:

{
  "$schema": "./node_modules/@umami/shiso/docs.schema.json",
  "name": { "$ref": "./config/name.json" },
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}

config/name.json:

"Acme docs"

When a reference resolves to an array or primitive value, that value replaces the whole object containing $ref. Sibling properties are ignored because there is no object to override.

Nested references and errors#

Referenced files can contain more $ref entries. Shiso resolves the complete tree and watches every referenced file during development, so changes reload without restarting the development server.

Shiso stops with an error when a reference:

• Points to a missing file or invalid JSON.
• Uses a URL, absolute path, non-JSON extension, or path outside the project.
• Creates a circular chain, such as a.json referencing b.json while b.json references a.json.

Run pnpm check to resolve all references and validate the resulting configuration without running a full build.