DocInsight resolves authored paths before it generates output URLs. Relative paths provide the most portable behavior across DocInsight, GitHub, and Visual Studio Code. Use a root-relative path when the path should start from a stable project or repository location.

A relative path starts from the directory that contains the Markdown file:

See [Installation](../getting-started/installation.md).

![Options dialog](images/options.png)

A relative path first resolves from the source file within its Markdown content entry. A local topic is resolved in that entry, and a local resource is copied with it when referenced. If the normalized path is not owned there, it may resolve through project.reference_root to another declared content owner or, for a resource, a project asset set. The output target must select the resolved owner.

A root-relative path begins with / and is resolved against project.reference_root. It is not an operating-system absolute path or a generated site URL.

The reference root defaults to the DocInsight project root. For this project layout:

my-library/
|-- docinsight.json
|-- docs/
|   `-- getting-started/
|       `-- installation.md
`-- images/
    `-- logo.svg

Markdown can refer to the topic and image by their paths from the project root:

See [Installation](/docs/getting-started/installation.md).

![Logo](/images/logo.svg)

DocInsight resolves the source path and its declared owner before it determines how to publish the target. A topic must be publishable content owned by the current project. A resource can belong to a Markdown content entry or a project asset set. The output target must select that owner, whose content binding or asset mount determines the published path. See Assets for ownership and selection rules.

The same Markdown path syntax uses different configured roots across authoring tools:

Path form	DocInsight	GitHub	VS Code
name, ./name, or ../name	Directory containing the Markdown file	Directory containing the Markdown file	Directory containing the Markdown file
/name	Configured project.reference_root	Repository root	Current workspace root

GitHub documents both file-relative and root-relative paths in Relative links and image paths in Markdown files. VS Code documents the corresponding editor behavior in Markdown path completions.

Prefer relative paths for nearby topics and resources. They keep the same meaning when a project directory moves or when a different folder is opened as the VS Code workspace.

Root-relative paths work consistently only when the DocInsight reference root, GitHub repository root, and VS Code workspace root identify the same directory. This is common for a standalone project. A monorepo requires additional configuration.

When docinsight.json is at the repository root, omit project.reference_root. Its default value, ., already makes the DocInsight reference root match the GitHub repository root.

In a monorepo, the DocInsight project root is usually below the repository root:

repository/
|-- products/
|   `-- my-library/
|       |-- docinsight.json
|       |-- docs/
|       |   `-- getting-started/
|       |       `-- installation.md
|       `-- images/
|           `-- logo.svg
`-- shared/

With the default reference root, /docs/getting-started/installation.md works in DocInsight but points at repository/docs/ on GitHub. To make the three tools use the repository root, set project.reference_root to ../.. and open repository/ as the VS Code workspace.

The property must resolve to the DocInsight project root or one of its ancestor directories. Its value is relative to the directory containing docinsight.json:

{
  "project": {
    "name": "my-library",
    "reference_root": "../.."
  }
}

To set the value during initialization, use --reference-root; see the init command reference.

Root-relative paths must then include the project directory from the repository root:

See [Installation](/products/my-library/docs/getting-started/installation.md).

![Logo](/products/my-library/images/logo.svg)

The common layouts are:

Layout	project.reference_root	Topic path
docinsight.json at repository root	Omit or use .	/docs/getting-started/installation.md
products/my-library/docinsight.json in a monorepo	../..	/products/my-library/docs/getting-started/installation.md

project.reference_root affects only root-relative paths. It does not change:

• Relative Markdown paths.

• Manifest paths such as content roots, asset roots, or output paths.

• Content or asset ownership.

• Generated mounts, routes, or public URLs.

A topic or resource must still belong to the current DocInsight project; a path to a sibling project is not supported.

If contributors may open different subdirectories as their VS Code workspace, prefer relative paths instead of relying on /.

Include and snippet sources must use relative paths and remain inside their Markdown content root. Delphi XML documentation resolves local resources relative to the .pas source file and does not currently support root-relative paths.

External URLs retain their normal URL semantics and are not resolved from the reference root.