# Markdown path compatibility

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.

## Relative paths

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

markdown

    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.

## Root-relative paths

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:

text

    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:

markdown

    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.

## GitHub and VS Code compatibility

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.

## Configure the reference root

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:

text

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

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:

markdown

    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 `/`.

## Other authored paths

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.