# Assets

DocInsight distinguishes content-local assets from project asset sets by ownership. Content-local assets belong to a content entry. Project asset sets establish ownership of files published independently of content.

## Content-local assets

A referenced resource is content-local when its resolved source file is owned by a declared content entry. That owner may differ from the entry containing the reference. DocInsight copies the resource with its owner when it is referenced; the output target must select that content entry. Do not also declare the resource under the top-level `assets` object.

Path syntax does not determine ownership. A relative path and a root-relative path can both identify a content-local asset when they resolve inside the content boundary. Each content type defines how it resolves authored resource paths and which source boundary applies.

For Markdown path resolution, see Markdown path compatibility and Add images and assets. For images in Delphi XML documentation, see Link to an image.

## Project asset sets

Define independently published files as named sets under the top-level `assets` object:

json

    {
      "assets": {
        "images": {
          "root": "assets/images",
          "files": ["**/*.png", "**/*.jpg", "**/*.svg"],
          "exclude": ["drafts/**"]
        },
        "downloads": {
          "root": "downloads",
          "files": ["*.zip", "examples/*.zip"]
        },
        "legal": {
          "files": ["LICENSE", "NOTICE"]
        }
      }
    }

`root` is optional and defaults to the directory that contains `docinsight.json`. It is the base directory for patterns and published relative paths. Setting `root` to `.` has the same effect as omitting it.

`files` is required and cannot be empty. It is the positive allowlist of files that the set can publish. `exclude` is optional and filters the `files` matches.

Avoid broad asset patterns

Do not use `"files": ["**/*"]` unless the asset root is a dedicated publish-only directory. The pattern also includes matching files added later and can unintentionally publish temporary, private, or sensitive files. Prefer explicit filenames or narrow patterns for the required file types and directories. Do not rely on `exclude` as a security boundary.

All resolved files must remain within `root`. File roots and selected members cannot traverse symbolic links, junctions, or other filesystem redirections; redirections are rejected even when their destination remains inside the project boundary.

When `mount` is omitted, DocInsight publishes a set under its name. For example, `assets/images/logo.svg` from the `images` set is published as `images/logo.svg`. Use `mount` only when the set needs a different output prefix.

An output target publishes only the project asset sets named by its optional `assets` array. Defining a set does not select it automatically. See Select project assets for target configuration.

## Asset ownership

For each output target, the selected asset sets establish ownership of their matching source files. A project asset referenced by published content must be owned by exactly one selected set. DocInsight reports an error when no selected set owns the file or when multiple selected sets make ownership ambiguous. Referencing a file does not select its asset set automatically.

A selected asset set publishes every file included by `files` and not removed by `exclude`, including files that authored content does not reference.

For Markdown path syntax and project asset references, see Markdown path compatibility, Add links and cross-references, and Add images and assets. For source-relative images in Delphi XML documentation, see Link to an image.

## Generated output

DocInsight detects output conflicts before writing files. Two asset sets, a project asset and a referenced content resource, or an asset and a generated page cannot publish different artifacts to the same path.

Builds record asset paths and content hashes in private output state. Later builds reuse unchanged files and remove stale files that are no longer selected, matched, or referenced. The `clean` command removes generated assets owned by the selected target.