# Content

Content entries define the documentation units that an output target can publish, such as Markdown guides and generated Delphi API reference. Configure named entries under `content`, then select them from one or more output targets.

## Configure Markdown content

A Markdown content entry selects a directory of authored topics:

json

    {
      "content": {
        "docs": {
          "title": "Documentation",
          "type": "markdown",
          "root": "docs",
          "mount": "/"
        }
      }
    }

`root` is resolved from the directory that contains `docinsight.json` and must remain inside that directory. It defines the entry's topic discovery and local resource boundary. Relative links first resolve in the current content entry; when the resolved path has another declared owner, the output target must also select that owner.

Use `files` to narrow the Markdown files that can be discovered. When it is omitted, DocInsight uses `**/*.md`. When present, the array cannot be empty:

json

    {
      "content": {
        "docs": {
          "title": "Documentation",
          "type": "markdown",
          "root": "docs",
          "files": ["guides/**/*.md", "reference/**/*.md"],
          "exclude": ["drafts/**", "private/**"]
        }
      }
    }

`files` and `exclude` patterns are matched relative to `root` and are case-insensitive. A single `*` does not cross a path separator; use `**` for nested directories.

A project can define multiple Markdown content entries. Each entry has its own root, topic identities, table of contents, publishing boundary, and default output mount. Relative and root-relative links may resolve across declared content owners when both entries are selected by the output target. Use an Xref when the link should depend on stable topic identity instead of a physical source path.

Place `toc.md` directly under a Markdown content root when the entry needs stable navigation and publishing order. Without it, DocInsight generates navigation from discovered topic paths. See Organize the table of contents for TOC syntax and publishing behavior, and Markdown path compatibility for relative and root-relative paths.

## Configure Delphi API content

Delphi API content uses a shared source-analysis context under `sources`. The source controls project discovery, analysis, and Xref namespaces. The content entry selects a publication view from that source:

json

    {
      "project": {
        "name": "mylibrary",
        "title": "MyLibrary"
      },
      "sources": {
        "main": {
          "type": "delphi",
          "root": ".",
          "files": ["Packages/MyLibrary.groupproj"],
          "xref": {
            "projects": {
              "MyLibrary.Tests": "mylibrary.tests"
            }
          },
          "options": {
            "compiler": "delphi_13",
            "platform": "Win32",
            "config": "Release",
            "defines": ["DOCS"]
          }
        }
      },
      "content": {
        "api": {
          "type": "delphi",
          "title": "API Reference",
          "source": "main",
          "filter": {
            "projects": {
              "include": ["MyLibrary", "MyLibrary.Tests"]
            },
            "units": {
              "exclude": ["*.Internal"]
            },
            "symbols": {
              "exclude": ["*.Deprecated"]
            }
          }
        }
      }
    }

The content name `api` controls publication and the default output mount; it is not an Xref namespace. In this example, ordinary Delphi projects use the default namespace `mylibrary` from `project.name`, while `MyLibrary.Tests` uses the `mylibrary.tests` project override.

Set `sources.<name>.root` to the base directory for project discovery. It defaults to the directory containing `docinsight.json`. Like Markdown and asset roots, a Delphi source root must be relative, cannot contain `..`, and must remain inside the DocInsight project directory without filesystem redirection. DocInsight accepts `.groupproj`, `.dproj`, `.dpr`, and `.dpk` project files.

The source `files` and `exclude` patterns are relative to its root. Together they define the direct project-entry file scope: `exclude` removes only files matched directly by `files`. It is not reapplied to projects or units reached while expanding a selected project group or project graph. For example, an excluded `.dproj` can still be analyzed when a selected `.groupproj` references it. Publication filters belong to the Delphi content entry, not the source.

### Configure Xref namespaces

The optional source `xref` object controls the stable namespaces exported by generated Delphi API topics. By default, every project in the source uses `project.name`. Set `xref.namespace` to replace that source-wide default and use `xref.projects` for exact project overrides:

json

    {
      "xref": {
        "namespace": "mylibrary.sdk",
        "projects": {
          "MyLibrary.Tests": "mylibrary.tests"
        }
      }
    }

Project override keys are exact, case-insensitive Delphi project names derived from `.dproj` filename stems; they do not accept wildcards. An override is the complete namespace. The priority is an exact project override, then the source-wide namespace, then `project.name`. Effective namespaces are normalized to lowercase. In the example above, `MyLibrary.Tests` uses `mylibrary.tests` and other projects use `mylibrary.sdk`.

Project overrides are useful when a program or library would otherwise repeat its project name. A package local ID starts at the unit, such as `MyLibrary.Collections/IList{T}`. A program or library named `MyLibrary.Tests` instead has a project-scoped local ID such as `mylibrary.tests/...`; with the default namespace, the full Xref is `mylibrary/mylibrary.tests/...`. Mapping that project to `mylibrary.tests` makes the shorter Xref `mylibrary.tests/...`. A source-wide `xref.namespace` changes the default but does not remove the project segment.

The source `root` controls filesystem discovery only. It does not establish an Xref namespace or change these namespace rules.

To publish a subset of the analyzed graph, use the Delphi content `filter`. Project, unit, and symbol filters accept independent `include` and `exclude` wildcard lists:

json

    {
      "content": {
        "api": {
          "type": "delphi",
          "source": "main",
          "filter": {
            "projects": {
              "include": ["MyLibrary*"],
              "exclude": ["*.Tests"]
            },
            "units": {
              "exclude": ["*.Internal"]
            },
            "symbols": {
              "exclude": ["*.Deprecated", "*.Internal*"]
            }
          }
        }
      }
    }

These are case-insensitive whole-name patterns, not file globs. `*` matches zero or more characters and `?` matches exactly one. See Configure API reference structure and filtering for the name matched by each field, the optional Xref namespace filter, and how inclusion and exclusion combine.

### Analysis options

Set `options.compiler` to the Delphi compiler version used for analysis. Set `platform` explicitly when the selected compiler supports more than Win32; Win32-only compilers default to `Win32`. Use `config`, `defines`, and `properties` when the project requires values other than their defaults.

By default, DocInsight discovers a local Delphi environment for an x86 IDE host. Select the x64 environment explicitly when needed:

json

    {
      "sources": {
        "main": {
          "type": "delphi",
          "files": ["Packages/MyLibrary.dproj"],
          "options": {
            "compiler": "delphi_13",
            "platform": "Win64",
            "environment": {
              "type": "local",
              "arch": "x64"
            }
          }
        }
      }
    }

For an environment without a local Delphi installation, provide the variables and search paths required to evaluate the projects:

json

    {
      "sources": {
        "main": {
          "type": "delphi",
          "files": ["Packages/MyLibrary.dproj"],
          "options": {
            "compiler": "delphi_13",
            "environment": {
              "type": "custom",
              "variables": {
                "BDS": "C:/Build/Delphi/37.0"
              },
              "search_paths": ["src", "$(BDS)/source"]
            },
            "platform": "Win64"
          }
        }
      }
    }

For generated page organization, inherited members, and publication filters, see Configure API reference structure and filtering.

## Publish content

Output targets select content entries by exact name. The order of names in a target's `content` array controls their top-level order in generated navigation.

Use `mount` when a content entry needs a specific output prefix. An entry with `"mount": "/"` is published at the target root. When `mount` is omitted, DocInsight uses the content entry name as its output prefix.

Content entries selected by the same output target can cross-reference each other. For example, Markdown topics can link to generated Delphi API pages, and Delphi XML documentation comments can link back to Markdown topics.

For content selection, target formats, destinations, and defaults, see Output targets.