# Output targets

Output configuration defines the generated formats and paths for a project. Each named target selects an ordered set of content entries, can select project asset sets, and can inherit or select separately configured site settings.

## Configure output targets

Define HTML and CHM targets under `output.targets`:

json

    {
      "output": {
        "default_targets": ["site"],
        "targets": {
          "site": {
            "type": "html",
            "path": "dist/docs/site",
            "content": ["docs", "api"]
          },
          "help": {
            "type": "chm",
            "path": "dist/docs/my-library.chm",
            "content": ["docs", "api"]
          }
        }
      }
    }

Relative target paths are resolved from the directory that contains `docinsight.json`; absolute paths are also accepted. Use `/` path separators and give each target its own path. The order of names in `content` controls the top-level order of those content entries in generated navigation.

## Select project assets

Use a target's optional `assets` array to publish named project asset sets:

json

    {
      "assets": {
        "images": {
          "root": "assets/images",
          "files": ["**/*.png", "**/*.svg"]
        }
      },
      "output": {
        "targets": {
          "site": {
            "type": "html",
            "path": "dist/docs/site",
            "content": ["docs", "api"],
            "assets": ["images"]
          }
        }
      }
    }

If `assets` is omitted, the target publishes no project asset sets. If present, it cannot be empty and must contain unique, exact names. Resources referenced from a selected content entry are copied automatically and are not listed here. For file selection and project asset references, see Assets.

## Keep team output local

For a manifest shared by a team, configure each target with a local generated-output path, such as `dist/docs/site`, and exclude that path from version control:

text

    /dist/docs/

Local output paths keep routine `build` and `clean` commands inside each team member's worktree. They also keep generated files out of commits.

Do not make a shared publishing location the default target path in a team manifest. When a publishing job deliberately needs a shared or deployment location, override the path for that command:

shell

    docinsight build --target site=Z:/docs/mylibrary

The override does not modify `docinsight.json`. For its behavior across `check`, `build`, `open`, and `clean`, see Override target output paths.

## Select default targets

Set `output.default_targets` to the targets used by `check`, `build`, and other project commands when the command line does not select targets explicitly. If `default_targets` is omitted, DocInsight selects all configured targets in canonical name order.

For command-line target selection, see Select output targets.

## HTML output

An HTML target writes a documentation site to a directory. HTML output uses the Learn theme.

### Configure page and link URLs

Use the target-local `urls` object to select public page URLs and generated internal-link styles:

json

    {
      "output": {
        "targets": {
          "site": {
            "type": "html",
            "path": "dist/docs/site",
            "content": ["docs", "api"],
            "urls": {
              "page": "clean",
              "link": "root_relative"
            }
          }
        }
      }
    }

Property | Values | Default | Effect
--- | --- | --- | ---
`page` | `html`, `clean` | `html` | `html` keeps `.html` page names. `clean` removes the extension from public page URLs and maps `index.html` to its directory.
`link` | `relative`, `root_relative` | `relative` | `relative` writes links from the current page. `root_relative` writes links from the selected site's `base_path`.

Use `root_relative` only when the output is hosted at a known base path. Configure that path in the default or named site settings.

When you run `docinsight open`, a target that uses clean page URLs or root-relative links is served through a local HTTP server. A target with the default HTML page URLs and relative links opens directly from the local file system.

## CHM output

A CHM target writes a compiled HTML Help file. Its `path` must name a file with the `.chm` extension.

Set the target-local `title` when the CHM window and artifact need a title different from the project title:

json

    {
      "type": "chm",
      "path": "dist/docs/my-library.chm",
      "title": "My Library Help",
      "content": ["docs", "api"]
    }

CHM builds require Microsoft HTML Help Workshop and `hhc.exe`. DocInsight normally finds the compiler from the Windows registry; set `DOCINSIGHT_HHC_TOOL` when it is installed in a nonstandard location.

## Generated output

Builds record generated pages, resources, and assets with their content hashes in private output state. Later builds reuse unchanged files, write changed files, and remove stale files owned by the previous build. Use the CLI to build documentation or clean generated output.