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.
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.
Define independently published files as named sets under the top-level assets object:
{
"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.
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.
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.