# DocInsight project

A DocInsight project is a documentation build and publishing boundary defined by a `docinsight.json` manifest. The manifest connects documentation inputs, assets, site settings, and output targets, and provides the shared project context used by the command-line interface and editor integrations.

A project can represent a standalone documentation site, documentation maintained alongside a product, generated API reference, or a combination of these forms.

## Project root

The directory containing `docinsight.json` is the DocInsight project root. Relative paths in the manifest are resolved from this directory unless otherwise specified.

Place the manifest at a level that contains the files managed by the project. Depending on the repository structure, this might be:

- the root of a dedicated documentation repository;

- the root of a product repository;

- a product or documentation directory within a monorepo.

DocInsight commands and editor integrations locate a project by searching the current directory and its ancestors for the nearest manifest. Keeping managed documentation, assets, and source inputs below the project root allows tools to discover and resolve them consistently.

## Project model

A project connects one or more inputs to one or more generated outputs:

- Content defines publishable Markdown documentation, generated API reference, or both, together with any source-analysis settings they require.

- Assets defines project-level files that output targets can publish alongside content-local assets.

- Site settings defines reusable identity and deployment metadata for documentation sites.

- HTML and CHM output defines named output targets and selects the content and project assets published by each target.

The model supports both simple and composed projects. A project might publish a single Markdown website, combine guides with generated Delphi API reference, or publish different content selections as separate websites and help files.

## Recommended project layout

A standalone documentation repository can use a simple layout:

text

    my-docs/
    |-- docinsight.json
    |-- docs/
    |   |-- overview.md
    |   `-- toc.md
    `-- site/
        |-- favicon.svg
        `-- robots.txt

Documentation maintained alongside a Delphi project might instead use this layout:

text

    my-library/
    |-- docinsight.json
    |-- docs/
    |   |-- overview.md
    |   `-- toc.md
    |-- Packages/
    |   |-- MyLibrary.dpk
    |   `-- MyLibrary.dproj
    `-- Source/
        `-- MyLibrary.Collections.pas

In either form, generated output typically goes in an ignored directory such as `dist/`, which is not shown. These directory names are conventions rather than requirements; configure paths that match the repository and deployment model.

## Related topics

- Initialize a project

- Project manifest