Overview | DocInsight Docs

  1. Guide
  2. Getting started

Overview

On this page

  1. Next steps

DocInsight is a local-first documentation system for building product documentation. It supports Markdown topics, API reference generated from Delphi source code, or both, and builds documentation websites, offline HTML, and CHM help.

The DocInsight command-line interface (CLI) is the primary way to initialize, check, build, open, and clean documentation projects, and to integrate documentation builds into CI workflows. For Delphi projects, the Delphi IDE extension helps you write and maintain XML documentation comments alongside the source code.

Next steps

  1. Install DocInsight.

  2. Activate DocInsight, or continue in trial mode.

  3. Follow the Quick start to create and build a documentation project.

Upgrading from an earlier version? See What's new in 2026.1.

Copyright © DevJet Software.
Built with DocInsight.


Install DocInsight | DocInsight Docs

  1. Guide
  2. Getting started

Install DocInsight

On this page

  1. Before you start
  2. Run the installer
  3. Verify the installation
    1. Verify the CLI
    2. Verify the Delphi IDE extension
  4. Silent installation
  5. Next steps

Install DocInsight before you create or build documentation projects.

Before you start

  • Use Windows 10 or Windows 11 on x64 or ARM64.

  • The Delphi IDE extension requires Delphi XE7 or later. Close any running Delphi IDE instances before installing the extension.

  • Microsoft HTML Help Workshop is required only if you build CHM output.

Run the installer

Download the current DocInsight Insiders installer from the official Download page, then run it.

During installation, you can select:

  • Add DocInsight to PATH (User Environment) to run docinsight from a terminal.

  • Delphi Extensions to install the extension for selected Delphi versions.

  • Microsoft HTML Help Workshop (CHM Compiler) to build CHM output.

DocInsight installs for the current Windows user and does not require administrator privileges.

Verify the installation

Verify the CLI

Open a new terminal so that it picks up the updated PATH, then run:

shell
docinsight --version

Verify the Delphi IDE extension

Open a supported Delphi version and check that the splash screen shows the DocInsight product version. After the IDE starts, check that the top-level DocInsight menu is available.

For supported Delphi versions and IDE architectures, see Delphi extension compatibility.

Silent installation

Use /silent to hide the normal setup wizard while keeping the installation progress window visible.

Use /verysilent to hide both the wizard and the progress window.

For a fully unattended installation, also consider /suppressmsgboxes to suppress most message boxes and /norestart to prevent an automatic restart.

For more options, see the Inno Setup command-line documentation.

Next steps

  • Activate DocInsight with a license, or continue in trial mode.

  • Follow the Quick start to create and build a documentation project.


Activate DocInsight | DocInsight Docs

  1. Guide
  2. Getting started

Activate DocInsight

On this page

  1. Activate from the CLI
  2. Activate from Delphi
  3. Trial mode
  4. Next steps

Activate DocInsight with the license email and license key from your purchase.

You can skip activation and use DocInsight in trial mode for evaluation.

Activate from the CLI

Run the license command:

shell
docinsight license set

Enter your license email and license key when prompted.

To view the current license status, run:

shell
docinsight license show

Activate from Delphi

If the Delphi IDE extension is installed, open Delphi and choose DocInsight > License... to manage your license.

Trial mode

Trial mode is for internal evaluation only. Generated output includes DocInsight trial notices and may not be published, redistributed, or used in production.

Activate DocInsight before using generated documentation outside internal evaluation.

Next steps

  • Follow the Quick start to create and build a documentation project.


Quick start | DocInsight Docs

  1. Guide
  2. Getting started

Quick start

On this page

  1. Create a documentation project
    1. Create a Markdown-only project
  2. Migrate a legacy project
  3. Check the documentation project
  4. Build and open the site
  5. Next steps

This quick start creates a DocInsight project that combines a Markdown guide with API reference generated from one or more existing Delphi projects. Follow it to check the project, build the HTML site, and open the site in your browser. If you have not installed DocInsight yet, see Install DocInsight.

If you already have a legacy .diproj manifest, skip the template workflow and migrate the existing project.

Create a documentation project

Open a terminal in the repository root that contains your Delphi projects, then run:

shell
docinsight init --template delphi

The initializer guides you through three settings:

  1. Enter the path to an existing .groupproj, .dproj, .dpr, or .dpk file, relative to the repository root, such as Packages/MyLibrary.dproj.

  2. Select the Delphi compiler version used by the project, such as delphi_13.

  3. Select the target platform to analyze, such as Win32.

DocInsight derives the project name and title from the current directory name. Pass --name and --title to set them explicitly:

shell
docinsight init --template delphi --name my-library --title "My Library"

The examples below assume the project root folder is named my-library, with Packages/MyLibrary.dproj selected for Delphi 13 and Win32.

The delphi template creates docinsight.json and a starter Markdown guide alongside the existing Delphi project:

text
my-library/
|-- docinsight.json
|-- docs/
|   |-- overview.md
|   `-- toc.md
`-- Packages/
    `-- MyLibrary.dproj

The generated manifest defines a Delphi source, Markdown guide content, Delphi API content, and an HTML output target that contains both:

json
{
  "edition": "2026",
  "project": {
    "name": "my-library",
    "title": "My Library"
  },
  "sources": {
    "main": {
      "type": "delphi",
      "files": ["Packages/MyLibrary.dproj"],
      "options": {
        "compiler": "delphi_13",
        "platform": "Win32"
      }
    }
  },
  "content": {
    "docs": {
      "title": "Guide",
      "type": "markdown",
      "root": "docs",
      "mount": "/"
    },
    "api": {
      "title": "API Reference",
      "type": "delphi",
      "source": "main"
    }
  },
  "output": {
    "default_targets": ["site"],
    "targets": {
      "site": {
        "type": "html",
        "path": "dist/docs/site",
        "content": ["docs", "api"]
      }
    }
  }
}

The generated docs/overview.md is the first guide topic. The generated docs/toc.md makes it the default topic and places it in the navigation. Edit these files as the guide grows.

Create a Markdown-only project

If you only need Markdown documentation, use the markdown template instead:

shell
docinsight init --template markdown

Migrate a legacy project

Import an existing .diproj manifest instead of selecting a template:

shell
docinsight init --from-legacy MyLibrary.diproj

DocInsight converts the legacy configuration to docinsight.json and creates starter Markdown guide files when needed.

Check the documentation project

Run docinsight check before building or publishing:

shell
docinsight check

The check command validates the project manifest, configured content, and source files without writing generated output. It analyzes the selected Delphi source and reports documentation problems it finds there.

If the command exits successfully, the project passed validation. Depending on the configured content and verbosity, a clean project may produce little or no output.

Build and open the site

Build the default output target:

console
$ docinsight build

Building MyLibrary...

✓ Built   site  dist/docs/site  103 pages

Built MyLibrary in 0.1s.
1 target built; 0 errors, 0 warnings.

The generated site is written to dist/docs/site and includes both the Markdown guide and Delphi API reference.

Open the generated site in your default browser:

shell
docinsight open

Next steps

  • Learn how project manifests are organized in Project manifest.

  • Learn how Markdown topics are structured in Markdown topics.

  • Learn how Delphi comments become generated reference pages in Delphi API documentation.


What's new in DocInsight 2026.1 | DocInsight Docs

  1. Guide
  2. What's new

What's new in DocInsight 2026.1

On this page

  1. Unified documentation projects
  2. Markdown authoring
  3. Cross-reference Markdown and API documentation
  4. HTML and CHM output
    1. HTML documentation sites
    2. CHM help files
    3. Expanded site configuration
  5. Redesigned command-line workflows
    1. Initialize a project
    2. Select and override output targets
    3. Improved diagnostics
    4. Build and open documentation
    5. Incremental builds and output verification
    6. Clean generated output
    7. Terminal progress and controls
  6. Updated Delphi IDE experience
  7. Toolchain and platform updates
  8. Website and documentation
  9. Known issues and limitations

DocInsight 2026.1 introduces a new project foundation for building connected Markdown and Delphi API documentation. Define your content and output targets in one project, then check and build HTML sites and CHM help files locally or in CI.

Unified documentation projects

The new docinsight.json manifest brings Markdown topics, Delphi source code, assets, site metadata, and output targets into one repository-native project. Publish Markdown, generated Delphi API reference, or both as an HTML site or CHM help file, with shared navigation and links between guides and API symbols.

For an introduction to the project model and recommended layout, see DocInsight project.

Existing .diproj projects remain supported. To adopt the new manifest when ready, see Migrate a legacy project, which uses docinsight init --from-legacy to import the existing configuration.

Markdown authoring

Write topics in the Markdown editor of your choice, then use DocInsight to check and build them. DocInsight Markdown is based on CommonMark and supports common GitHub Flavored Markdown extensions, including tables, task lists, and strikethrough. Authors can use familiar Markdown together with DocInsight features for larger documentation sets.

For supported syntax and authoring features, see Markdown syntax, Use variables, Add callouts, and Add links and cross-references.

Cross-reference Markdown and API documentation

Markdown topics and generated Delphi API reference can link to each other in both directions through the same documentation model. Xrefs identify their targets independently of generated paths, so links remain stable when an output mount or URL layout changes. In Markdown, use a labeled xref: link or an Xref autolink to reference an API symbol:

markdown
See [IList<T>](xref:mylibrary/MyLibrary.Collections/IList{T}).

See <xref:mylibrary/MyLibrary.Collections/IList{T}>.

The labeled form controls the link text. The autolink uses the target's display name, so it does not need a separate label.

Markdown topics can also configure an Xref base and document-local aliases in front matter, then use WikiLinks as shorthand for labeled or unlabeled Xrefs:

markdown
---
xref:
  base: mylibrary/MyLibrary.Collections
  aliases:
    types: mylibrary/MyLibrary.Types
---

See [[IList{T}.IndexOf]] and [[types/IComparer{T}|Comparer]].

In Delphi XML documentation comments, use xref with <see> for an inline link or <seealso> for a related-topic link back to Markdown:

pascal
/// <summary>
///   Creates a list. See the <see xref="docs/collections">collections guide</see>
///   for usage patterns.
/// </summary>
/// <seealso xref="docs/collections">
///   Collections guide
/// </seealso>
class function CreateList<T>: IList<T>; overload; static;

For complete examples and linking rules, see Add links and cross-references and Link API symbols and topics.

HTML and CHM output

Publish the same Markdown guides and generated API reference as an HTML site or a compiled CHM help file.

HTML documentation sites

HTML output presents guides and API reference in one site with title search and light and dark themes.

A DocInsight HTML site containing a guide and generated Delphi API reference

Explore the MyLibrary sample documentation site.

HTML targets now support clean URLs and root-relative links through the target's urls.page and urls.link settings. Clean URLs omit .html from public page addresses, while root-relative links resolve internal navigation and assets from the configured site base path. The settings can be used independently or together to match the URL layout of the hosting environment, including sites deployed below a domain subpath.

For configuration, see Configure page and link URLs.

CHM help files

The new Learn-style CHM output presents both content types in one navigable help system.

Markdown guides and Delphi API reference in a Learn-style CHM help file

Expanded site configuration

The new project manifest supports a default site configuration or multiple named entries under sites. Each output target can select a site configuration and a set of content entries, allowing one project to publish distinct documentation sites with their own identity, deployment settings, and content. See Site settings.

Configure formats, destinations, and content selection independently for each output target.

Redesigned command-line workflows

The CLI now supports the complete project workflow, from initializing and checking a project to building, opening, and cleaning its outputs. Named target selection, output path overrides, verification, and additional command options provide more control over local and automated workflows.

Initialize a project

The new docinsight init command creates the docinsight.json manifest and starter content. Use the delphi template to initialize a Markdown guide and Delphi API documentation together:

shell
docinsight init --template delphi

For a Markdown-only project, use the markdown template instead.

To import an existing .diproj instead of starting from a template, use the legacy project migration workflow.

See Initialize a project for templates and initialization options.

Select and override output targets

The new project model manages generated output as named targets. A project can designate output.default_targets for routine commands; if the setting is not configured, DocInsight selects every target.

Use no selection option for the defaults, --target to select by name, or --all-targets to select every target:

shell
docinsight build
docinsight build --target site
docinsight build --all-targets

The check, build, and clean commands can operate on multiple targets; open selects one target.

Append =PATH to any repeated --target value to override that target's output path for one command:

shell
docinsight build --target site=Z:/docs/mylibrary --target help=Z:/docs/mylibrary.chm

Each override applies only to its named target, and a repeated target without =PATH continues to use its configured path. Overrides do not change the manifest. This lets a team keep local, ignored output paths in the shared manifest while a publishing job deliberately writes to shared or deployment locations. See Select output targets for complete selection and override rules.

Improved diagnostics

The check and build commands now report stable diagnostic codes, precise source locations, annotated source excerpts, and actionable help. This makes documentation problems such as unresolved cross-references and malformed XML easier to identify and fix. See Check documentation.

CLI diagnostics highlighting XML documentation problems and suggesting a fix

Build and open documentation

Use --open to open one target after a successful build, or run docinsight open to open existing output without rebuilding:

shell
docinsight build --target site --open
docinsight open site

Both commands handle the configured HTML URL style automatically. For clean URLs or root-relative links, DocInsight starts a local HTTP server and opens the site in your browser; output with default HTML URLs and relative links opens directly from the local file system. See Build documentation and Open documentation.

Incremental builds and output verification

DocInsight now builds output incrementally. Each build runs the complete documentation pipeline and records generated paths and content hashes in a private output manifest. When publishing the planned output, DocInsight leaves unchanged files in place, writes changed files, and removes stale generated files.

Let DocInsight manage generated output

Before the first 2026.1 build, remove existing generated files from each HTML target's configured path. Files created before the output manifest are not tracked and can remain as stale output.

Afterwards, manage the target directory with docinsight build and docinsight clean. Do not edit generated files or store unrelated files there; they may be overwritten by a later build. Change the documentation sources and rebuild instead.

By default, DocInsight trusts the output manifest when reusing a destination file. Use --verify-output to hash reusable destination files and rewrite any whose contents no longer match the planned output:

shell
docinsight build --verify-output

For state reuse and verification behavior, see Incremental builds.

Clean generated output

The new docinsight clean command removes files owned by previous builds without recursively deleting the output root or unrelated files:

shell
docinsight clean --target site

Use --dry-run to review the operation first. Clean supports the same default, named, all-target, format, and output-path selection rules as other output commands. It is available for docinsight.json projects and does not clean output from legacy .diproj projects. See Clean generated output.

Terminal progress and controls

The check and build commands now display progress indicators for long-running work. DocInsight automatically adapts colors, progress indicators, and file hyperlinks to the current terminal; use --color, --progress, and --hyperlinks with auto, always, or never to control them explicitly. The corresponding --no-color, --no-progress, and --no-hyperlinks options provide shortcuts for disabling these features.

Use --no-input to prevent prompts in scripts and CI. See Control console output and logs and Automate CLI workflows for usage and complete option details.

Updated Delphi IDE experience

The Delphi IDE extension now supports high-DPI icons and the IDE dark theme. Documentation Inspector provides a focused surface for viewing and editing the XML documentation comment associated with the declaration at the source-editor caret.

Documentation Inspector in the Delphi IDE dark theme

DocInsight 2026.1 also adds source analysis for the Delphi 13.1 WinARM64EC target. For supported Delphi IDE versions and host architectures, see Delphi extension compatibility.

Toolchain and platform updates

The installed docinsight.exe entry point is now a stable launcher rather than a version-specific CLI. It dispatches ordinary commands to the configured default toolchain, so PATH entries and scripts can remain unchanged when toolchains are updated. Prefix a command with +TOOLCHAIN to select another installed toolchain for one invocation:

shell
docinsight +insiders check

Use docinsight toolchain list to list installed toolchains and docinsight toolchain default to show the current default. DocInsight 2026.1 also adds a native ARM64 build of the CLI alongside the x64 build.

Website and documentation

The DocInsight website and product documentation are now available online.

Known issues and limitations

  • The docinsight.json workflow in 2026.1 is CLI-centered and does not include a GUI project wizard or an integrated Markdown editor. Use docinsight init to create a project, edit Markdown in your preferred editor, and run docinsight check to validate the project.

  • The XML documentation editor in the Delphi IDE extension does not yet provide a dedicated Xref target picker. As a workaround, select Insert link > URI and manually enter an xref: URI, such as xref:docs/collections.

  • The Delphi IDE Documentation Project Wizard still creates and builds legacy .diproj projects.

  • The generated HTML site's search currently matches topic titles only. Full-text search is planned for a future release.


DocInsight project | DocInsight Docs

  1. Guide
  2. Set up a documentation project

DocInsight project

On this page

  1. Project root
  2. Project model
  3. Recommended project layout
  4. Related topics

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


Initialize a project | DocInsight Docs

  1. Guide
  2. Set up a documentation project

Initialize a project

On this page

  1. Initialize Markdown and Delphi documentation
  2. Set the project identity
  3. Replace an existing manifest
  4. Import a legacy project
  5. Related topics

docinsight init creates a docinsight.json manifest and, when requested, starter Markdown documentation. Run it from the directory that should become the DocInsight project root.

Migrating an existing .diproj project? Skip to Import a legacy project.

Initialize Markdown and Delphi documentation

Open a terminal in the directory that should become the project root, then use the delphi template to combine authored Markdown with generated Delphi API reference:

shell
docinsight init --template delphi

DocInsight prompts for one or more Delphi project files or glob patterns, optional exclusions, the Delphi compiler version, and the target platform. It then creates the manifest and a starter Markdown guide, and configures both the guide and API reference in one HTML output target.

If the project needs only Markdown documentation, use the markdown template instead:

shell
docinsight init --template markdown

Both templates create docs/overview.md and docs/toc.md. Their HTML target writes to dist/docs/site.

Set the project identity

DocInsight derives the project name and title from the project directory. Use --name and --title to set them explicitly:

shell
docinsight init --template delphi --title "My Library" --name my-library

Replace an existing manifest

Initialization stops when docinsight.json already exists. Use --force only when you intend to replace it with a newly generated manifest:

shell
docinsight init --template delphi --force

--force replaces docinsight.json but does not overwrite existing starter Markdown files.

Import a legacy project

Use --from-legacy instead of a template to migrate an existing .diproj project:

shell
docinsight init --from-legacy MyLibrary.diproj

DocInsight converts the legacy configuration to docinsight.json and creates starter Markdown guide files when needed.

After initialization, edit docinsight.json to adjust content, source analysis, site settings, and output targets.

Related topics

  • DocInsight project

  • Project manifest

  • init command reference


Project manifest | DocInsight Docs

  1. Guide
  2. Set up a documentation project

Project manifest

On this page

  1. Manifest structure
  2. Project metadata
  3. Check the project configuration
  4. Related topics

A docinsight.json manifest defines a DocInsight project by connecting project metadata, sources, content, assets, site settings, and output targets. The directory containing it is the project root.

The file uses UTF-8 JSONC (JSON with Comments). In addition to standard JSON syntax, it accepts // line comments, /* ... */ block comments, and trailing commas.

Manifest structure

The top-level sections have separate responsibilities:

  • project identifies the documentation project and defines shared metadata.

  • variables defines reusable manifest values.

  • sources defines source-analysis contexts, such as a Delphi project and compiler settings.

  • content defines publishable Markdown and API documentation.

  • assets defines named project-level file sets that output targets can publish.

  • i18n defines the project-wide default locale.

  • site and sites define default and named rendering and deployment metadata.

  • output defines named output targets and the content and project asset sets each target publishes.

Project metadata

Every manifest identifies the documentation project with a project object:

json
{
  "project": {
    "name": "mylibrary",
    "title": "MyLibrary",
    "description": "A documentation sample project for Delphi",
    "copyright": "Copyright © DevJet Software. All Rights Reserved.",
    "homepage": "https://docinsight.github.io",
    "repository": "https://github.com/docinsight/mylibrary"
  }
}

name is the required, case-insensitive project identifier; use a short ASCII value such as mylibrary or my-library. It is also the default Xref namespace for Delphi sources. title is the user-facing project name. Other fields provide shared descriptions, links, and notices.

Check the project configuration

After editing docinsight.json, run a documentation check from the project root or one of its subdirectories:

shell
docinsight check

DocInsight validates the manifest and checks Markdown files and Delphi XML documentation comments for problems such as invalid configuration, broken links, and unresolved cross-references. It does not generate output.

Related topics

  • DocInsight project

  • Initialize a project

  • Check documentation

  • Manifest reference


Content | DocInsight Docs

  1. Guide
  2. Set up a documentation project

Content

On this page

  1. Configure Markdown content
  2. Configure Delphi API content
    1. Configure Xref namespaces
    2. Analysis options
  3. Publish 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.


Site settings | DocInsight Docs

  1. Guide
  2. Set up a documentation project

Site settings

On this page

  1. Configure the default site
  2. Configure hosted site URLs
  3. Configure named sites
  4. Select a site for an output target

A site definition supplies shared identity, presentation metadata, and public URL context to site-aware output targets. It does not define an output format or destination. Configure formats, paths, and content selection under output.targets instead.

Configure the default site

Use the top-level site object as the default site definition:

json
{
  "project": {
    "name": "my-library",
    "copyright": "Copyright © Example Company. All Rights Reserved."
  },
  "site": {
    "title": "My Library Documentation",
    "title_suffix": " | My Library Docs",
    "description": "Guides and API reference for My Library.",
    "origin": "https://docs.example.com",
    "base_path": "/my-library/",
    "footer": {
      "notice": "{{project.copyright}}"
    }
  }
}

HTML and CHM targets inherit this definition when their target-local site property is omitted. When the top-level site object is absent, targets still derive values such as the title and description from project metadata.

Use these fields for site identity and presentation:

Property | Purpose
title | Site title used by renderers.
title_suffix | Text appended to generated page titles.
description | Default site and page description.
favicon | Published .ico, .svg, or .png asset used by web output.
footer.notice | Notice displayed in the generated footer.

The title, title_suffix, description, and footer.notice fields support manifest variable references such as {{project.title}}.

Configure hosted site URLs

Use these fields to describe where an HTML site is published:

Property | Purpose
origin | HTTP or HTTPS origin, such as https://docs.example.com.
base_path | URL path under the origin; defaults to /.
robots | Optional content for the HTML robots meta directive; omitted by default.

origin must contain only an HTTP or HTTPS origin, without a path, query, or fragment. base_path starts with / and is normalized with a trailing slash.

When robots is omitted, DocInsight does not add a robots meta directive. Use noindex,follow for a publicly reachable preview, staging, or secondary site that should not appear in search results but whose links may still be followed. This directive is not access control; protect private documentation with authentication or network restrictions.

An HTML target can use the selected site's base_path when generating root-relative links. Page URL and internal-link styles remain target-specific settings; see Configure page and link URLs.

Configure named sites

Use the top-level sites object when targets need different site definitions. Each named site has the same fields as the default site:

json
{
  "site": {
    "title": "My Library Documentation",
    "origin": "https://docs.example.com"
  },
  "sites": {
    "offline": {
      "title": "My Library Offline Help",
      "footer": {
        "notice": "Offline documentation"
      }
    }
  }
}

A named site is a full replacement for the top-level site; DocInsight does not merge the two definitions. Defining a single named site does not select it automatically.

Select a site for an output target

Use the target-local site property to control which definition a target uses:

json
{
  "output": {
    "targets": {
      "site": {
        "type": "html",
        "path": "dist/docs/site",
        "content": ["docs", "api"]
      },
      "help": {
        "type": "chm",
        "path": "dist/docs/my-library.chm",
        "title": "My Library Help",
        "site": "offline",
        "content": ["docs", "api"]
      }
    }
  }
}

Target setting | Result
Property omitted | Inherit the top-level site when it exists.
"site": "offline" | Use the named definition at sites.offline.
"site": false | Do not inherit or select a site definition.

CHM output reuses applicable rendering metadata from the selected site. The CHM window and artifact use the target's title or, when it is omitted, the project title. For target formats and target-local settings, see Output targets.


Output targets | DocInsight Docs

  1. Guide
  2. Set up a documentation project

Output targets

On this page

  1. Configure output targets
  2. Select project assets
  3. Keep team output local
  4. Select default targets
  5. HTML output
    1. Configure page and link URLs
  6. CHM output
  7. Generated output

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.


Assets | DocInsight Docs

  1. Guide
  2. Set up a documentation project

Assets

On this page

  1. Content-local assets
  2. Project asset sets
  3. Asset ownership
  4. Generated output

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.


Variables | DocInsight Docs

  1. Guide
  2. Set up a documentation project

Variables

On this page

  1. Define user variables
  2. Use built-in variables
  3. Related topics

Variables provide reusable values for authored documentation and selected manifest metadata. Define user variables in the top-level variables object in docinsight.json; DocInsight also provides built-in project and system variables.

Define user variables

A variable can be a string, a link, or an object whose fields contain those values:

json
{
  "variables": {
    "product_name": "My Library",
    "company": {
      "name": "DevJet Software",
      "homepage": {
        "type": "link",
        "label": "DevJet Software",
        "href": "https://devjetsoftware.com/"
      }
    },
    "documentation_title": "{{project.title}} documentation"
  }
}

Variable names start with an ASCII letter and contain only ASCII letters, digits, or underscores. Lookup is ASCII case-insensitive, but DocInsight preserves the spelling in the manifest. The same rules apply to each segment of a dotted variable path.

Each key in the top-level variables object defines a variable. Project names do not implicitly define variables, even when project.name is a valid variable identifier.

Do not use a reserved variable name such as sys, workspace, project, site, target, content, topic, page, or api.

String variables can reference other variables. Link labels and targets are literal and do not expand variable references.

Use built-in variables

The project variable exposes project metadata such as name, title, description, homepage, repository, license, and copyright. For example, {{project.title}} renders the configured project title.

The built-in sys.docinsight variable renders a link to DocInsight and exposes its label and href fields.

Related topics

  • Use variables in Markdown

  • Manifest reference


Manifest examples | DocInsight Docs

  1. Guide
  2. Set up a documentation project

Manifest examples

On this page

  1. Markdown with Delphi API reference
  2. Related topics

Use the following complete manifest as a starting point. Update project names, source paths, site metadata, and output paths to match the repository.

Markdown with Delphi API reference

This manifest defines project and site metadata, a Delphi source, Markdown guide content, Delphi API content, a project asset set, and HTML and CHM output targets:

json
{
  "edition": "2026",
  "project": {
    "name": "my-library",
    "title": "My Library",
    "description": "Developer documentation for My Library.",
    "homepage": "https://docinsight.github.io",
    "repository": "https://github.com/docinsight/mylibrary",
    "copyright": "Copyright © DevJet Software. All Rights Reserved.",
    "license": "Apache-2.0"
  },
  "sources": {
    "main": {
      "type": "delphi",
      "files": ["Packages/MyLibrary.dproj"],
      "options": {
        "compiler": "delphi_13",
        "platform": "Win32"
      }
    }
  },
  "content": {
    "docs": {
      "title": "Guide",
      "type": "markdown",
      "root": "docs",
      "mount": "/"
    },
    "api": {
      "title": "API Reference",
      "type": "delphi",
      "source": "main"
    }
  },
  "assets": {
    "images": {
      "root": "assets/images",
      "files": ["**/*.png", "**/*.svg"]
    }
  },
  "site": {
    "title": "My Library Documentation",
    "title_suffix": " | My Library Docs",
    "description": "Guides and reference for My Library.",
    "origin": "https://docinsight.github.io",
    "base_path": "/my-library/",
    "footer": {
      "notice": "{{project.copyright}}\nBuilt with {{sys.docinsight}}."
    }
  },
  "output": {
    "default_targets": ["site"],
    "targets": {
      "site": {
        "type": "html",
        "path": "dist/docs/site",
        "content": ["docs", "api"],
        "assets": ["images"]
      },
      "chm": {
        "type": "chm",
        "path": "dist/docs/chm/mylibrary.chm",
        "content": ["docs", "api"],
        "assets": ["images"]
      }
    }
  }
}

Both targets publish the guide at the output root, the API reference under api/, and the selected image files under images/. The site target remains the default; select chm explicitly when you need the help file.

Related topics

  • Project manifest

  • Manifest reference


Markdown topics | DocInsight Docs

  1. Guide
  2. Write Markdown documentation

Markdown topics

On this page

  1. Create a topic file
  2. Add a topic title
  3. Add topic metadata
  4. Keep unfinished topics as drafts

A topic is one authored page in a Markdown content entry. This topic explains the structure and publication metadata of a topic file. Before writing topics, configure Markdown content in the project manifest.

Create a topic file

Create topic files under a Markdown content root:

text
docs/
|-- getting-started/
|   |-- overview.md
|   `-- installation.md
|-- markdown/
|   `-- topics.md
`-- toc.md

With this layout, getting-started/overview.md and markdown/topics.md are topic paths relative to the docs content root.

Use one topic for one task, concept, or reference page. Use stable, lowercase kebab-case filenames:

text
docs/
`-- markdown/
    |-- content.md
    |-- topics.md
    `-- table-of-contents.md

Add a topic title

Use one H1 at the top of each topic:

markdown
# Configure logging

Use this topic to configure diagnostic logging.

Start each topic with one H1. DocInsight uses it as the generated page title and does not duplicate it in the topic body.

Use H2 through H6 for sections inside the topic:

markdown
# Build output

## Select a target

## Open generated files

Add topic metadata

Add YAML front matter when the topic needs a stable ID, description, keywords, tags, draft state, document Xref bindings, or custom metadata:

markdown
---
id: guide/install
description: Install DocInsight before running the CLI.
keywords: [install, setup]
tags: [getting-started]
draft: true
xref:
  base: mylibrary/MyLibrary.Collections
  aliases:
    list: mylibrary/MyLibrary.Collections/IList{T}
---

# Installation

The opening and closing front matter fences must be --- on their own lines.

DocInsight uses the topic ID in Xrefs from other content entries and Delphi XML documentation. By default, it derives the ID from the topic path without the file extension. Set id when cross-references must remain stable after the file moves. Topic IDs must be unique within the Markdown content entry.

DocInsight reads these front matter keys:

  • id: Stable topic ID. It must be unique within the Markdown content entry. If omitted, DocInsight derives the ID from the topic path without the file extension.

  • title: Topic title used when the file does not contain an H1.

  • description: Topic description used by generated output.

  • keywords: String or list of strings.

  • tags: String or list of strings.

  • draft: Boolean. Use true for unfinished topics. Draft topics are excluded from normal published output.

  • xref: Optional document Xref scope with base and aliases. See Configure a document Xref scope.

Unknown keys are preserved as extra metadata for downstream processing. The former name key does not set the topic ID; use id instead.

Keep unfinished topics as drafts

Set draft: true while a topic is under review:

markdown
---
draft: true
---

# New deployment guide

Draft topics are left out of normal published output. If a draft topic has a topic entry in toc.md, DocInsight omits that entry from the generated table of contents. A link from a published topic to a draft topic produces a check diagnostic, so remove the link or finish the draft before publishing.

Drafts are not an access-control mechanism. The source file remains in the project, so do not use drafts for confidential content.

A topic is published only when it is selected by the Markdown content entry, that content entry is included by the selected output target, and the topic is not excluded as a draft. When the content root has toc.md, the TOC provides the main publishing shape. For details, see Organize the table of contents.


Markdown syntax | DocInsight Docs

  1. Guide
  2. Write Markdown documentation

Markdown syntax

On this page

  1. Text and emphasis
  2. Headings
  3. Lists
  4. Block quotes
  5. Tables
  6. Thematic breaks
  7. Comments

DocInsight supports standard Markdown syntax and common GitHub Flavored Markdown extensions. This topic covers the syntax used most often in product documentation; the other topics in this section describe DocInsight-specific authoring features.

Text and emphasis

Separate paragraphs with a blank line. Use a trailing backslash or two trailing spaces when you need a hard line break inside a paragraph.

Source

markdown
This is one paragraph with _emphasis_, **strong emphasis**,
~~strikethrough~~, and `inline code`.

This is another paragraph.\
This line starts after a hard line break.

Result

This is one paragraph with emphasis, strong emphasis, strikethrough, and inline code.

This is another paragraph.
This line starts after a hard line break.

Headings

Use ATX headings with one to six # characters:

markdown
# Topic title

## Main section

### Subsection

Use one H1 as the topic title. Use H2 through H6 to organize sections within the topic. See Markdown topics for DocInsight title behavior.

Lists

Use hyphens for unordered lists and numbers for ordered lists:

markdown
- Markdown topics
- Delphi API reference
- Project assets

1. Check the documentation.
2. Build the selected target.
3. Open the generated output.

Indent a list item to create a nested list. Use task-list markers when items have a checked state:

Source

markdown
- [x] Configure the project
- [ ] Write the documentation
- [ ] Build the output

Result

  • Configure the project

  • Write the documentation

  • Build the output

Block quotes

Prefix quoted content with >:

Source

markdown
> Generated files should not be edited by hand.

Result

Generated files should not be edited by hand.

Use a callout instead when the content is a note, tip, important notice, warning, or danger message rather than a quotation.

Tables

Use a header row and delimiter row to create a table:

Source

markdown
| Field     | Purpose                       |
| :-------- | :---------------------------- |
| `root`    | Markdown content root.        |
| `exclude` | Files removed from discovery. |

Result

Field | Purpose
root | Markdown content root.
exclude | Files removed from discovery.

In the delimiter row, :--- aligns a column left, ---: aligns it right, and :---: centers it.

Thematic breaks

Use three or more hyphens on a line by themselves to separate parts of a topic:

Source

markdown
---

Result

Comments

Use an HTML comment to leave information for authors without adding it to the generated HTML:

Source

markdown
<!-- Explain why this section is intentionally empty. -->

Result

No visible output is generated.

Comments are not private

DocInsight omits HTML comments from generated HTML, but other Markdown renderers, preprocessors, and publishing tools may preserve or expose them differently. The comments also remain visible in the Markdown source, repository, source packages, and backups. Do not use them for confidential information, credentials, license keys, or private source code.


Organize the table of contents | DocInsight Docs

  1. Guide
  2. Write Markdown documentation

Organize the table of contents

On this page

  1. Create the root TOC
  2. Add navigation sections
  3. Link a navigation group
  4. Link to topics
  5. Split large navigation
  6. Understand publishing order

Add toc.md to a Markdown content root when the documentation needs stable navigation and publishing order. The root toc.md is not published as a topic. It describes the shape of the generated documentation for that Markdown content entry.

Create the root TOC

Place toc.md directly under the Markdown content root:

text
docs/
|-- toc.md
|-- index.md
|-- installation.md
`-- guide/
    `-- usage.md

Use front matter to select the default topic:

markdown
---
default_topic: index.md
---

default_topic selects the topic opened first by generated output that supports a default page. The path is resolved relative to the toc.md file. Set the content entry's display title with content.<name>.title in the project manifest. See Content.

Add navigation sections

Use H2 headings for top-level navigation groups and H3 headings for groups nested under the preceding H2. Use list items for the topics inside each group:

markdown
## Get started

- [Overview](index.md)
- [Installation](installation.md)

## Guide

- [Usage](guide/usage.md)

Linked list items become pages in navigation. Plain list items become groups:

markdown
## Guide

- Setup
  - [Installation](installation.md)
  - [Configuration](configuration.md)
- [Usage](guide/usage.md)

List indentation creates nested navigation. Keep nesting shallow enough that readers can scan the sidebar.

Link a navigation group

Use a linked heading when a navigation group also has a landing topic:

markdown
## [Command-line tools](cli/index.md)

### Basics

- [Install](cli/install.md)

### [Advanced](cli/advanced.md)

- [Configuration](cli/configuration.md)

The heading title becomes the navigation group title. The heading link becomes the group target.

Link to topics

TOC topic links use normal relative Markdown paths:

markdown
- [Installation](installation.md)
- [Usage](guide/usage.md)

Paths in a root toc.md are resolved relative to the Markdown content root. Paths in a nested toc.md are resolved relative to that nested toc.md file.

TOC links must point to topics inside the same Markdown content entry. Use a cross-reference when a topic needs to point at generated content from another content entry.

Split large navigation

Use a nested toc.md when one area has its own navigation:

text
docs/
|-- toc.md
`-- guide/
    |-- toc.md
    |-- installation.md
    `-- usage.md

Link to the directory from the parent TOC:

markdown
## Documentation

- [Overview](index.md)
- [Guide](guide/)

The linked directory must contain its own toc.md:

markdown
# Guide

- [Installation](installation.md)
- [Usage](usage.md)

DocInsight replaces the directory link with the nested TOC group. The nested TOC's H1 becomes the group title.

Understand publishing order

When a Markdown content root has toc.md, DocInsight uses it as the primary publishing shape. Topics linked from the TOC are published and appear in navigation.

DocInsight also keeps:

  • The root index.md landing page when it exists.

  • The configured default_topic.

  • Markdown topics reached through links from already published topics.

When a Markdown content root does not have toc.md, DocInsight still discovers Markdown topics selected by root, files, and exclude, then generates automatic navigation from the topic paths.


Add links and cross-references | DocInsight Docs

  1. Guide
  2. Write Markdown documentation

Add links and cross-references

On this page

  1. Link to another topic
  2. Link to a section
  3. Link to an index topic
  4. Resolve across content owners
  5. Cross-reference another content entry
    1. Configure a document Xref scope
    2. Use WikiLinks as Xref shorthand
  6. Cross-reference from API comments
  7. Keep cross-references stable
  8. Link to external pages
  9. Link to project assets

Use the narrowest link type that matches the target:

Target | Use
Topic with a stable source path | Relative or root-relative Markdown link
Topic whose stable identity matters | Cross-reference (Xref)
Generated API reference topic | Cross-reference (Xref)
External page | URL link
Download, sample, or other project asset | Path beginning with /

Cross-references use stable identities instead of physical source paths or generated output paths. They are preferred when content may move or when a mount, target, or reference structure can change its output path.

Link to another topic

Use normal Markdown links when a topic has a stable source path:

markdown
See [Installation](installation.md).

The target may belong to the current content entry or another declared content entry selected by the output target. Use an Xref when you want the link to survive a source-file move.

Relative paths are resolved from the source topic directory:

text
docs/
|-- getting-started/
|   |-- overview.md
|   `-- installation.md
`-- markdown/
    `-- topics.md

From docs/markdown/topics.md, link back to the getting started topic like this:

markdown
See [Overview](../getting-started/overview.md).

Link to a section

Add a heading anchor after the topic path:

markdown
See [Install the CLI](installation.md#install-the-cli).

The heading anchor should match the generated anchor for the heading text. Keep headings stable when other topics link to them.

Link to an index topic

A directory link resolves to index.md when that topic exists:

markdown
See [Markdown](markdown/).

Use a directory link when the target is the landing topic for that folder. Use the explicit file path when linking to a specific topic:

markdown
See [Topics](markdown/topics.md).

Resolve across content owners

Relative paths first resolve inside the source topic's content entry. If a topic is not owned there, DocInsight can resolve it through project.reference_root to another declared Markdown content entry. For example, a topic in docs can link to a topic owned by internals:

markdown
[Internal design](../internals/design.md)

The output target must select both content entries. The path does not select or publish internals automatically. If multiple entries own portable-equivalent paths, the reference is ambiguous. Generated content without an authored file path should be linked by Xref.

Cross-reference another content entry

An Xref can resolve only when the selected output target publishes both the source content entry and the content entry that exports the target:

json
{
  "output": {
    "targets": {
      "site": {
        "type": "html",
        "path": "dist/site",
        "content": ["docs", "api"]
      }
    }
  }
}

A provider-qualified Xref address has a namespace followed by the target identity:

text
namespace/id

Markdown topics use the content entry name as the namespace. Delphi API topics instead use the effective namespace for their Delphi project. By default, that namespace is the DocInsight project name. For example:

Target | Namespace
Markdown content entry docs | docs
Delphi API project in project MyLibrary | mylibrary
Delphi project MyLibrary.Tests with an override | mylibrary.tests

Configure Delphi API namespaces with sources.<name>.xref.namespace and exact project overrides under sources.<name>.xref.projects. See Configure Xref namespaces.

Markdown topics use their topic IDs as identities. Delphi API topics use source-owned structural identities and accept case-insensitive Pascal declaration spelling in authored Xrefs. Generated paths and mounts do not change these identities.

Use a Markdown link whose target is xref:namespace/id:

markdown
See [Installation](xref:docs/guide/install).

See [IList<T>](xref:mylibrary/MyLibrary.Collections/IList{T}).

Use an Xref autolink when the target's display name is the appropriate link text:

markdown
See <xref:mylibrary/MyLibrary.Collections/TCollections>.

An Xref autolink does not need a separate link label.

An Xref can also include a heading anchor:

markdown
See [List methods](xref:mylibrary/MyLibrary.Collections/IList{T}#methods).

Configure a document Xref scope

Every Markdown topic has its own Xref scope. Use the optional front matter xref.base for its default binding and xref.aliases for document-local named bindings:

markdown
---
xref:
  base: mylibrary/MyLibrary.Collections
  aliases:
    list: mylibrary/MyLibrary.Collections/IList{T}
    add: mylibrary/MyLibrary.Collections/IList{T}.Add
---

Base and alias values are absolute bindings without a leading /. Alias names are case-insensitive and cannot contain /.

Use these address forms with the example above:

Address | Meaning
/mylibrary/MyLibrary.Collections/IList{T}.Add | Start from the root Xref scope
. | Reference the configured base itself
./IList{T}.Add | Start explicitly from the configured base, bypassing aliases
IList{T}.Add | Try an alias, then the effective base
list | Reference the list alias itself
list/Add | Continue with Add from the list alias

For an ordinary unrooted address, DocInsight tries a document alias first, then the effective base: xref.base when configured, otherwise the root Xref scope. A leading / skips the document scope and starts from the root.

. and ./... require xref.base; without it, references such as [[.]] and <xref:.> are unresolved. . also requires the base itself to identify an entity. After DocInsight selects a binding, a failed continuation does not fall back elsewhere. When a base is configured, use / for an absolute provider Xref.

The leading / in an Xref address is unrelated to the leading / in a Markdown topic or asset path. Xrefs use the root Xref scope; Markdown paths use project.reference_root.

Use WikiLinks as Xref shorthand

WikiLinks are shorthand for Xrefs:

WikiLink | Equivalent Xref
[[IList{T}.Add]] | <xref:IList{T}.Add>
[[list/Add|Add an item]] | [Add an item](xref:list/Add)

They use the same lookup rules as other Xrefs. WikiLinks are not recognized inside code, raw HTML, or another link's label. Escape the first bracket as \[[ to keep the text literal.

Document bases, aliases, and WikiLinks apply to Markdown topics. They do not change how an xref attribute in Delphi XML documentation is resolved.

Use a normal relative or root-relative Markdown link when the target's source path is the contract you want to preserve.

Cross-reference from API comments

Use cref for a Delphi symbol in the analyzed compilation environment:

pascal
/// <summary>
///   Creates a list. See <see cref="IList{T}" />.
/// </summary>
class function CreateList<T>: IList<T>; static;

Use xref for an explicit DocInsight Xref, including a link to a Markdown topic:

pascal
/// <seealso xref="docs/guide/install">
///   Installation guide
/// </seealso>

Use href for an external URL. For more examples, see Link API symbols and topics.

Keep cross-references stable

When other content links to a Markdown topic by Xref, keep its topic ID stable. Set an explicit id if the topic may move:

markdown
---
id: guide/install
---

# Installation

When an Xref does not resolve, check that:

  • The selected output target publishes the target content entry.

  • The namespace matches the Markdown content entry name or the Delphi project's effective Xref namespace.

  • The target identity exists and is not a draft.

  • The selected anchor exists in the target.

Link to external pages

External URLs and URI links are kept as href links:

markdown
[DocInsight](https://docinsight.dev)
[Email support](mailto:support@example.com)

Links that start with # or ? are also kept as raw href links.

Link to project assets

Use a root-relative path for a download, sample, or other file published by a project asset set:

markdown
[Download the sample project](/downloads/sample-project.zip)
[Download the starter sample](/downloads/starter.zip)

DocInsight resolves the path against project.reference_root. The file must be included by one project asset set, and every output target that publishes the topic must select that set. See Markdown path compatibility and Assets for configuration and selection rules.

Use a relative Markdown path for a nearby file. DocInsight first looks for a resource owned by the current content entry, then may resolve another declared content or asset-set owner through project.reference_root. The output target must select the final owner.

For images, use image syntax and the guidance in Add images and assets.


Add images and assets | DocInsight Docs

  1. Guide
  2. Write Markdown documentation

Add images and assets

On this page

  1. Use clear image text
  2. Add a topic image
  3. Group topic image sets
  4. Reuse an image across topics
  5. Reference external images

Prefer relative paths for Markdown images, especially when documentation is reviewed in GitHub:

markdown
![Options dialog](options-dialog.png)

GitHub previews relative image paths from the repository, and DocInsight collects relative topic images into generated output.

For downloads, samples, and other non-image files, see Add links and cross-references.

Use clear image text

Write alt text that identifies the image:

markdown
![Project options dialog](project-options.png)

Add an optional title only when the generated output should expose extra hover text:

markdown
![Project options dialog](project-options.png "Project options")

Add a topic image

The image path is resolved relative to the topic file:

text
docs/
|-- configuration.md
`-- options-dialog.png

From docs/configuration.md, link to the image like this:

markdown
![Options dialog](options-dialog.png)

Group topic image sets

When one topic has several local images, put them in a topic-named folder beside the topic:

text
docs/
|-- configuration.md
`-- configuration/
    |-- options-dialog.png
    `-- output-targets.png

From docs/configuration.md, link to the images like this:

markdown
![Options dialog](configuration/options-dialog.png)

Reuse an image across topics

Keep shared Markdown images in a common directory inside the Markdown content root:

text
docs/
|-- images/
|   `-- logo.svg
`-- guide/
    `-- overview.md

From docs/guide/overview.md, reference the shared image with a relative path:

markdown
![Shared logo](../images/logo.svg)

To use an image from a project asset set instead, use its root-relative path:

markdown
![Product logo](/assets/images/logo.svg)

Every output target that publishes the topic must select the asset set that owns the file. See Markdown path compatibility and Assets for asset-set configuration.

Reference external images

External image URLs can be used for images that stay hosted elsewhere:

markdown
![Status badge](https://example.com/status.svg)

External images are less portable than project-local images. HTML output may load them from the network when the page is viewed. CHM output is offline-oriented, so remote images may not be available to readers. Prefer project-local images for screenshots, diagrams, and documentation that must build repeatably or work offline.


Add callouts | DocInsight Docs

  1. Guide
  2. Write Markdown documentation

Add callouts

On this page

  1. Add a callout
  2. Choose a callout type
    1. Note
    2. Tip
    3. Important
    4. Warning
    5. Danger
  3. Set a custom title
  4. Use GitHub-style alerts

Use callouts when a note, recommendation, requirement, or risk needs to stand apart from the normal task flow.

Add a callout

Start a callout with ::: and its type, then close it with another ::: line:

markdown
::: note
Use `toc.md` when navigation order matters.
:::

Callout bodies support normal Markdown, including multiple paragraphs, lists, links, and code blocks.

Choose a callout type

DocInsight provides five callout types:

Type | Use for
note | Helpful context that is worth noticing
tip | Optional advice or a faster path
important | Information readers must know before continuing
warning | A risk that may cause incorrect results, broken output, or other recoverable problems
danger | A risk of data loss, security exposure, or another serious consequence that may be difficult to reverse

The following examples show the default title and visual treatment for every type.

Note

Use a note for supporting context that helps readers understand the current task.

Note

Use toc.md when navigation order matters.

Tip

Use a tip for optional advice, a shortcut, or a more efficient approach.

Tip

Run docinsight check before building to find authoring problems without writing output.

Important

Use an important callout for information readers must know before continuing.

Important

Content entries must be included in the same output target before they can cross-reference each other.

Warning

Use a warning when an action may cause incorrect results, broken output, or another problem that requires corrective action.

Warning

Changing mount changes generated output paths and may break existing links.

Danger

Use a danger callout when an action may cause data loss, expose private information, or have another serious consequence that is difficult to reverse.

Danger

Do not publish an asset set that contains credentials or other private files.

Set a custom title

Use the title attribute when the default title does not describe the message:

markdown
::: important title="Before you publish"
Run `docinsight check` and review the selected output target.
:::

Use GitHub-style alerts

DocInsight also recognizes GitHub-style alerts in existing Markdown:

markdown
> [!NOTE]
> Use `toc.md` when navigation order matters.

NOTE, TIP, IMPORTANT, and WARNING map to the matching callout types. CAUTION maps to danger. Prefer the native ::: syntax when authoring new content because it supports callout attributes and nested Markdown directly.


Add code blocks | DocInsight Docs

  1. Guide
  2. Write Markdown documentation

Add code blocks

On this page

  1. Add a fenced block
  2. Choose a language
  3. Configure code display

Use fenced code blocks for commands, manifest fragments, source snippets, and Markdown syntax examples. A fenced block keeps whitespace intact and gives DocInsight a language id for syntax highlighting.

Add a fenced block

Put three backticks before and after the code:

markdown
```pascal
var
  Items: IList<string>;
begin
  Items := TCollections.CreateList<string>;
end;
```

Add the language id after the opening fence:

markdown
```json
{
  "output": {
    "default_targets": ["site"]
  }
}
```

The first word after the opening fence is the language identifier.

Choose a language

The Learn theme provides syntax highlighting for these commonly used identifiers:

Content | Language identifiers
Plain text | text
Delphi and Pascal | pascal, delphi
Web and markup | html, xml, markdown
Data and configuration | json, yaml, toml, ini
Query and patch text | sql, diff
Shell source | bash, sh, powershell, bat, cmd

Use semantic identifiers for commands and transcripts:

Identifier | Use for
shell | Commands intended to work across shells, without output
bash | Bash-specific commands or scripts
powershell | PowerShell commands or scripts
console | Generic interaction or output when the command language is not important
shell-session | A shell transcript containing literal prompts, commands, and output
powershell-session | A PowerShell transcript containing literal prompts, commands, and output

Use shell for command-only examples and console for command output when prompt-aware highlighting is not needed. In session blocks, prompts are part of the authored content and remain copyable.

Keep a shell command on one line when it should work across terminals. Line continuation is shell-specific: Bash uses a trailing \, PowerShell uses a trailing backtick (`), and Command Prompt uses a trailing ^. Use bash, powershell, bat, or cmd when an example depends on one of those syntaxes.

An unknown language identifier is preserved, but the Learn theme displays it without syntax highlighting.

Configure code display

Add attributes after the language identifier. Use braces when you use the #id or .class shorthand:

markdown
```pascal {title="Collections.pas" line-numbers=20 highlight="2,3-4" #create-list-example .compact}
function CreateList<T>: IList<T>;
begin
  Result := TCollections.CreateList<T>;
end;
```

DocInsight renders the example as follows:

Collections.pas
function CreateList<T>: IList<T>;
begin
  Result := TCollections.CreateList<T>;
end;

The displayed line numbers begin at 20, while highlight="2,3-4" highlights the second through fourth source lines. The id and class attributes are added to the generated HTML but do not necessarily produce a visible change unless the theme or custom styles use them.

Code blocks support these display attributes:

Attribute | Purpose
title | Adds a title above the code block. Quote a title that contains spaces.
line-numbers | Shows line numbers beginning at 1. Set line-numbers=N to begin at the positive integer N.
highlight | Highlights one-based code lines and inclusive ranges, such as "2,4-6".
#id | Adds an HTML id attribute. This shorthand requires braces.
.class | Adds an HTML class. This shorthand requires braces and can be repeated.

Highlight numbers refer to lines inside the fenced block, even when line-numbers=N changes the displayed line numbers. docinsight check reports unsupported attributes, invalid values, and highlighted lines outside the block.

The #id and .class shorthands require braces; the equivalent id="..." and class="..." attributes can be used without shorthand syntax.


Use variables | DocInsight Docs

  1. Guide
  2. Write Markdown documentation

Use variables

On this page

  1. Reference variables
  2. Related topics

Use {{...}} references to insert configured and built-in variables into authored Markdown. Variables can render text or links.

Reference variables

Use {{name}} or a dotted path such as {{company.name}} in Markdown text:

markdown
# {{documentation_title}}

{{product_name}} is maintained by {{company.homepage}}.

DocInsight expands variables in paragraphs, headings, lists, tables, and TOC labels. A link-valued variable renders as a link.

Objects cannot be rendered directly; reference one of their renderable fields instead. The value of project.name does not define another variable.

Variables do not expand inside inline code, fenced code blocks, raw HTML, or Markdown link destinations. Prefix the opening braces with a backslash to write a literal reference, such as \{{product_name}}.

Related topics

  • Variables


Delphi API documentation | DocInsight Docs

  1. Guide
  2. Document Delphi APIs

Delphi API documentation

DocInsight generates API reference directly from Delphi projects. Source analysis supplies the API structure, declarations, signatures, and symbol relationships; XML documentation comments supply the descriptions and guidance shown on generated reference pages.

First configure a Delphi source and content entry, then add /// XML documentation comments to the public declarations that readers need to understand. DocInsight generates pages for projects, units, types, and members selected by the API content entry.

DocInsight analyzes source using the compiler, environment, platform, configuration, conditional symbols, and project properties from the manifest. The Delphi source also owns the default Xref namespace and any per-project namespace overrides. The Delphi content entry uses filter.projects, filter.units, and filter.symbols to choose which analyzed declarations to publish.

Use the topics in this section to write XML documentation comments, link symbols and documentation topics, and configure the generated reference structure and symbol filters. An output target can publish the resulting API reference together with Markdown documentation.


Write XML documentation comments | DocInsight Docs

  1. Guide
  2. Document Delphi APIs

Write XML documentation comments

On this page

  1. Choose documentation sections
  2. Document units and types
  3. Document methods and return values
  4. Document properties
  5. Describe constraints and exceptions
  6. Add usage examples
  7. Format documentation text
  8. Write well-formed XML
  9. Check the documentation

DocInsight combines Delphi declarations with XML documentation comments to generate API reference. Place a consecutive block of /// comments immediately before the declaration it describes:

pascal
/// <summary>
///   Provides a resizable array-backed list.
/// </summary>
TArrayList<T> = class(TInterfacedObject, IList<T>)
end;

Write the documentation on the declaration in the interface section whenever possible. Describe the API contract that callers need rather than repeating information already visible in the declaration.

If you use the Delphi IDE extension, open Documentation Inspector to edit common XML documentation sections in a visual editor without writing the XML markup by hand. Use Documentation Explorer to browse declarations and review their rendered documentation. The comments remain stored with the declarations in Delphi source.

Choose documentation sections

Use a summary for the main description, then add only the sections needed by the declaration:

Element | Purpose
<summary> | Concise description of the declaration
<typeparam> | Role of a generic type parameter
<param> | Meaning and constraints of a method parameter
<returns> | Result returned by a function
<value> | Value exposed by a property
<remarks> | Behavior, ownership, side effects, or usage guidance
<exception> | Exception and the condition that raises it
<example> | Focused usage example
<seealso> | Related symbol, documentation topic, or external resource

A consistent order makes source comments easier to review: summary, type parameters, parameters, return or property value, remarks, exceptions, examples, and related links.

Document units and types

Place a unit comment before the unit declaration. Use the summary to define the unit's responsibility and remarks to identify its main entry points or important design context:

pascal
/// <summary>
///   Defines the public collection abstractions and factory methods for MyLibrary.
/// </summary>
/// <remarks>
///   The primary entry points are <see cref="IList{T}" />,
///   <see cref="IDictionary{TKey,TValue}" />, and
///   <see cref="TCollections" />.
/// </remarks>
unit MyLibrary.Collections;

For a type, describe what it represents and when callers should use it. Document every generic type parameter by its declared name:

pascal
/// <summary>
///   Provides a resizable array-backed implementation of
///   <see cref="IList{T}" />.
/// </summary>
/// <typeparam name="T">
///   The type of values in the list.
/// </typeparam>
/// <remarks>
///   This class is the default list implementation returned by the factory
///   methods on <see cref="TCollections" />.
/// </remarks>
TArrayList<T> = class(TInterfacedObject, IList<T>)
end;

Document methods and return values

Describe what the method does, what each parameter means, and how callers should interpret the result. The name on <param> and <typeparam> must match the declaration. Use <paramref> and <typeparamref> when referring to those names in prose:

pascal
/// <summary>
///   Compares two values and returns their relative order.
/// </summary>
/// <param name="Left">
///   The first value to compare.
/// </param>
/// <param name="Right">
///   The second value to compare.
/// </param>
/// <returns>
///   A value less than zero if <paramref name="Left" /> precedes
///   <paramref name="Right" />, zero if they are equal, or a value greater
///   than zero if <paramref name="Left" /> follows <paramref name="Right" />.
/// </returns>
function Compare(const Left, Right: T): Integer;

Document each overload independently. An overload should describe its own parameters, defaults, behavior, and result rather than relying on the comment for another declaration.

Document properties

Use <summary> to describe what the property provides and <value> to describe the value itself. Put ownership rules, mutation behavior, and other constraints in <remarks>:

pascal
/// <summary>
///   Gets a value indicating whether the list owns its objects.
/// </summary>
/// <value>
///   True when the list frees contained objects; otherwise, false.
/// </value>
/// <remarks>
///   Owned objects are freed when they are removed, when the list is cleared,
///   or when the list is destroyed.
/// </remarks>
property OwnsObjects: Boolean read FOwnsObjects;

For an indexed property, use <param> for each index parameter and <value> for the value read or written.

Describe constraints and exceptions

Use <remarks> for behavior that applies beyond the main summary. Use one <exception> for each exception that forms part of the public contract, and describe the condition that raises it:

pascal
/// <summary>
///   Gets the value at the specified index.
/// </summary>
/// <param name="Index">
///   The zero-based index of the value to get.
/// </param>
/// <returns>
///   The value at the specified index.
/// </returns>
/// <exception cref="EArgumentOutOfRangeException">
///   <paramref name="Index" /> is less than zero or greater than or equal to
///   <see cref="IReadOnlyCollection{T}.Count" />.
/// </exception>
function GetItem(Index: Integer): T;

Do not list every implementation exception. Document exceptions that callers can reasonably anticipate and handle.

Add usage examples

Place executable sample code inside <example> and <code>. Set lang="delphi" to enable Delphi syntax highlighting:

pascal
/// <summary>
///   Creates a resizable list of values.
/// </summary>
/// <typeparam name="T">
///   The type of values in the list.
/// </typeparam>
/// <returns>
///   A new <see cref="IList{T}" /> instance.
/// </returns>
/// <example>
///   <code lang="delphi">
///     var
///       Names: IList&lt;string&gt;;
///     begin
///       Names := TCollections.CreateList&lt;string&gt;;
///       Names.AddRange(['Ada', 'Grace']);
///     end;
///   </code>
/// </example>
class function CreateList<T>: IList<T>; static;

Keep examples focused on the declaration being documented. Use realistic names and ensure the sample remains valid when the API changes.

Format documentation text

Use XML elements to add structure and meaning inside documentation sections:

Element | Use for
<para> or <p> | A separate paragraph
<c> | An identifier, literal, or short code expression
<code> | A code block
<paramref> | A reference to a method parameter
<typeparamref> | A reference to a generic type parameter
<see> | An inline link
<list> | A bullet list, numbered list, or table
<note> | A note, tip, warning, or other callout
<b>, <i>, and related elements | Emphasis when wording alone is insufficient

Use formatting sparingly. Prefer clear sentences and short paragraphs over heavily marked-up descriptions. For cref, xref, external links, and local resources, see Link API symbols and topics.

Write well-formed XML

The text in /// comments is parsed as XML. Close every element, quote attribute values, and escape characters that would otherwise be interpreted as markup:

pascal
/// <summary>
///   Returns an <c>IList&lt;T&gt;</c> when A &amp; B are available.
/// </summary>

Use &lt;, &gt;, and &amp; for literal <, >, and & characters in XML content. Delphi generic syntax in the declaration itself remains unchanged.

Check the documentation

Run a documentation check after adding or changing XML comments:

shell
docinsight check

The check reports malformed XML and unresolved cross-references with source locations and corrective guidance. Before publishing, verify that summaries state purpose, parameter names match the declaration, return values and exceptions describe observable behavior, and examples still reflect the current API.


Link API symbols and topics | DocInsight Docs

  1. Guide
  2. Document Delphi APIs

Link API symbols and topics

On this page

  1. Link to a Delphi symbol
  2. Link to an external page
  3. Link to a documentation topic
  4. Link to an image
  5. Refer to parameters and type parameters

Use <see> for an inline link and <seealso> for an entry in the generated related-links section. Choose the target attribute by what you are linking to:

Attribute | Target
cref | Symbol that Delphi source analysis can resolve
href | External page
xref | Topic exported by the DocInsight documentation system

Link to a Delphi symbol

Use cref for a symbol in the analyzed Delphi compilation environment:

pascal
/// <summary>
///   Creates a new <see cref="IList{T}" /> instance.
/// </summary>
class function CreateList<T>: IList<T>; static;

DocInsight resolves cref by Delphi symbol identity rather than by a generated output path. When the referenced symbol has a published API topic, the generated link points to that topic.

Link to an external page

Use href for an external URL:

pascal
/// <seealso href="https://docinsight.github.io/mylibrary/">
///   MyLibrary documentation
/// </seealso>

Link to a documentation topic

Use xref for an explicit DocInsight cross-reference. The value contains the target Xref namespace and source-owned topic identity. Delphi API topics use the effective namespace assigned to their Delphi project by the source's xref settings:

pascal
/// <seealso xref="mylibrary/MyLibrary.Collections/TCollections">
///   TCollections
/// </seealso>

When project.name is mylibrary and the source has no namespace override, mylibrary is the default namespace. The Delphi content name, such as api, does not become part of the Xref. Package local IDs start at the unit. Program and library local IDs also include the Delphi project name; use an exact project namespace override when that would produce a redundant Xref such as mylibrary/mylibrary.tests/.... The override shortens it to mylibrary.tests/....

Markdown topics continue to use their content entry name as the namespace, so an API comment can link to a guide in the same documentation project like this:

pascal
/// <summary>
///   See the <see xref="docs/collections">collections guide</see> for usage patterns.
/// </summary>
/// <seealso xref="docs/collections">
///   Collections guide
/// </seealso>

For the Delphi source namespace configuration and project override precedence, see Configure Xref namespaces. For Markdown topic identities, see Add links and cross-references.

Link to an image

Use <img> with a relative src path to include an image in XML documentation. DocInsight resolves the path from the .pas file containing the comment:

pascal
/// <remarks>
///   The following diagram shows the collection hierarchy.
///   <img src="./images/collection-hierarchy.png" alt="MyLibrary collection hierarchy" />
/// </remarks>

The src value must be a relative filesystem path. Paths beginning with /, operating-system absolute paths, and URLs are not supported. The resolved image must remain inside the configured Delphi source root; paths and symbolic links that escape it are rejected. For ownership and publishing rules, see Content-local assets.

Refer to parameters and type parameters

Use <paramref> and <typeparamref> for parameter and type-parameter names in inline text:

pascal
/// <summary>
///   Gets the value at the specified <paramref name="Index" />.
/// </summary>
function GetItem(Index: Integer): T;


Configure API reference structure and filtering | DocInsight Docs

  1. Guide
  2. Document Delphi APIs

Configure API reference structure and filtering

On this page

  1. Configuration overview
  2. Organize generated reference topics
  3. Configure generated page paths
  4. Configure inherited members
  5. Control published API symbols
    1. Filter by semantic name
    2. Filter by visibility
    3. Filter by source section
    4. Exclude one declaration

Use the Delphi entry under content to control how DocInsight organizes generated API reference and which symbols it publishes. These settings are separate from the source-analysis options under sources. First, configure a Delphi source and content entry.

Configuration overview

The following expanded content entry shows semantic name filters together with the structure, reference, section, and visibility options:

json
{
  "content": {
    "api": {
      "type": "delphi",
      "source": "main",
      "structure": {
        "toc": {
          "scope": "project"
        },
        "path": {
          "project": "auto"
        }
      },
      "reference": {
        "inherited_members": "linked"
      },
      "filter": {
        "projects": {
          "include": ["MyLibrary*"],
          "exclude": ["*.Tests"]
        },
        "units": {
          "exclude": ["*.Internal"]
        },
        "symbols": {
          "exclude": ["*.Deprecated", "*.Internal*"]
        },
        "sections": {
          "implementation": false
        },
        "visibility": {
          "private": false,
          "strict_private": false,
          "protected": true,
          "strict_protected": true
        }
      }
    }
  }
}

The project, unit, and symbol filters in this example are sample publication constraints; omit any dimension to select all names in it. The remaining values shown are their effective defaults. You normally omit fields that keep their defaults and set only the values you want to change. When omitted, strict_private follows private, and strict_protected follows protected.

Organize generated reference topics

Use structure.toc.scope to choose how generated API navigation is divided:

Value | Navigation structure
unified | One TOC for the entire Delphi content entry
project | A project list with a separate TOC view for each project
unit | A project list with a separate TOC view for each unit

The default is project.

Configure generated page paths

Use structure.path.project to control whether generated API paths contain a project or package segment:

Value | Project path segment
none | Never included
auto | Included for programs and libraries, but not packages
always | Always included

The default is auto.

Configure inherited members

Use reference.inherited_members to control inherited members on generated type pages:

Value | Type-page behavior
linked | List inherited members that resolve to published API topics
none | List only members declared by the type

The default is linked.

Control published API symbols

Control publication at the project, unit, declaration-section, visibility, or individual-symbol level:

  • Use sources.<name>.files and exclude to select direct project-entry files during discovery.

  • Use the Delphi content entry's filter block to select Xref namespaces, projects, units, and symbols and to control implementation declarations and member visibility.

  • Use <exclude /> in an XML documentation comment to omit one declaration.

Filter by semantic name

The four semantic dimensions each accept the same name-filter object:

Property | Name matched
filter.xref_namespaces | Effective Xref namespace assigned to a project
filter.projects | Delphi project name derived from the .dproj filename stem
filter.units | Declared fully qualified unit name
filter.symbols | Unit-qualified symbol name without a parameter list or overload signature

Each name filter accepts include, exclude, or both. Every present array must be non-empty. Omitting the dimension selects every name in it; omitting only include also starts from every name. Patterns in one array are alternatives, then exclude is applied after include, so exclusion wins when both match.

Patterns are case-insensitive and match the complete semantic name. They are wildcard patterns rather than filesystem globs: * matches zero or more characters, ? matches exactly one, and all other characters are literal. A . has no special boundary behavior, so * can match across qualified-name segments. / and \\ are not allowed.

filter.xref_namespaces uses the namespace selected by the source's xref settings. filter.projects applies to every project with a matching portable name; project groups are discovery containers and are not matched. Unit patterns apply to every occurrence of the qualified unit name in an eligible project. Symbol patterns select an entire overload family because parameter types and overload signatures are not part of the matched name.

The dimensions combine by containment: a symbol is publishable only when its project passes both xref_namespaces and projects, its unit passes units, and the symbol passes symbols plus the section and visibility rules. Declarations omitted from publication remain available for analysis and cross-reference resolution.

Filter by visibility

Public, published, and automated declarations are always included. Protected and strict protected members are included by default; private and strict private members are excluded by default. Set filter.visibility.private, strict_private, protected, or strict_protected only when you want to override that behavior.

Filter by source section

Interface declarations are always eligible for publication. Implementation declarations are excluded by default. Set filter.sections.implementation to true when generating internal documentation that should include them.

Exclude one declaration

Add <exclude /> to the XML documentation comment for a declaration that should remain in source but should not have a published API topic:

pascal
/// <exclude />
procedure InternalResetCache;

For all Delphi content fields and accepted values, see the Manifest reference.


Check documentation | DocInsight Docs

  1. Guide
  2. Check, build, and automate

Check documentation

On this page

  1. Read diagnostics
  2. Related topics

From the project root or one of its subdirectories, run docinsight check to validate the documentation without writing generated output:

shell
docinsight check

The command validates the manifest and selected content, including Markdown topics and TOCs, Delphi API sources, links, and output configuration. It reports problems without writing generated output.

Read diagnostics

Diagnostics include a severity, a stable code, and a message. When a problem has a source location, DocInsight also shows the affected range and, when available, guidance for fixing it:

console
warning[DI2501]: malformed XML documentation: unescaped XML text `<T>`
   ┌─ Source\Base\Patterns\Spring.Patterns.Specification.pas:74:60
   │
74 │   ///   Provides the abstract base class for ISpecification<T>.
   │                                                            ^^^
   │
   = help: escape literal angle brackets as `&lt;T&gt;`

Fix reported problems and run docinsight check again. If the normal output does not contain enough detail, write a diagnostic log.

Related topics

  • Select a project manifest

  • Select output targets

  • check command reference


Build documentation | DocInsight Docs

  1. Guide
  2. Check, build, and automate

Build documentation

On this page

  1. Simulate a build
  2. Open after building
  3. Incremental builds
  4. Related topics

From the project root or one of its subdirectories, run docinsight build to generate the configured output targets:

shell
docinsight build

To validate the project without writing output first, see Check documentation.

Simulate a build

Use --dry-run to validate the build plan without writing output files:

shell
docinsight build --dry-run

Open after building

Use --open to open the built output when the build finishes:

shell
docinsight build --target site --open

build --open requires exactly one selected output target. Pass --target when the default selection contains more than one target. To open existing output without rebuilding it, see Open generated documentation.

Incremental builds

DocInsight records generated paths and content hashes in private output state. On later builds, it reuses unchanged files, writes changed files, and removes stale files owned by the previous build. Files that DocInsight does not own are not treated as generated output.

By default, DocInsight trusts its output state when reusing a destination file. Use --verify-output to hash reusable destination files and rewrite any file whose contents differ from the planned output:

shell
docinsight build --verify-output

CHM compilation still runs when a CHM target is built because hhc.exe produces the final file.

Use Clean generated output when you want to remove generated files instead of updating them incrementally.

Related topics

  • Select a project manifest

  • Select output targets

  • build command reference


Open generated documentation | DocInsight Docs

  1. Guide
  2. Check, build, and automate

Open generated documentation

On this page

  1. Select an output target
  2. Open HTML output
  3. Open CHM output
  4. Open after building
  5. Related topics

From the project root or one of its subdirectories, run docinsight open to open existing generated output:

shell
docinsight open

The command opens output from the selected target without running another build.

Select an output target

open requires exactly one selected output target. If the default selection contains more than one target, pass the target name:

shell
docinsight open --target site

If the target was built with an output path override, pass the same override to open it:

shell
docinsight open --target site=Z:/docs/mylibrary

Open HTML output

How DocInsight opens an HTML target depends on its URL settings:

  • With the default HTML page URLs and relative links, DocInsight opens the generated entry page directly from the local file system.

  • With clean page URLs or root-relative links, DocInsight starts a local HTTP server, opens the site in your browser, and keeps serving until you press Ctrl+C.

The local server supports the configured URL behavior; it does not rebuild or live-update the documentation.

Open CHM output

For a CHM target, DocInsight opens the generated .chm file.

If the output is missing or stale, build the documentation first.

Open after building

Use build --open to build and open one target in a single command:

shell
docinsight build --target site --open

Related topics

  • Select a project manifest

  • Select output targets

  • open command reference


Clean generated output | DocInsight Docs

  1. Guide
  2. Check, build, and automate

Clean generated output

On this page

  1. Clean an overridden output
  2. Review files before cleaning
  3. Related topics

From the project root or one of its subdirectories, run docinsight clean to remove output files owned by previous builds of the selected targets:

shell
docinsight clean

Cleaning removes build output, not source documentation. DocInsight uses private output state written by earlier builds to remove owned files and empty generated directories. It does not recursively delete the output root or files that are not recorded as generated output.

Warning

Do not edit generated output. clean removes owned files even when their contents have changed since the last build.

Clean an overridden output

If a target was built with an output path override, pass the same override to clean the files owned at that location:

shell
docinsight clean --target site=Z:/docs/mylibrary

A selected target without an override uses the path configured in the manifest and does not clean an alternate build location.

Review files before cleaning

Use --dry-run to simulate cleaning without deleting files:

shell
docinsight clean --dry-run

The clean command supports docinsight.json manifests. It does not support legacy .diproj manifests.

Related topics

  • Select a project manifest

  • Select output targets

  • clean command reference


Select a project manifest | DocInsight Docs

  1. Guide
  2. Check, build, and automate

Select a project manifest

On this page

  1. Use the discovered manifest
  2. Specify a manifest

Commands that operate on an existing project need a docinsight.json or legacy .diproj manifest. Let DocInsight discover the project during routine work, or use --manifest when a command needs an explicit project context.

Use the discovered manifest

When a command runs inside a documentation project, DocInsight searches the current directory and then its parent directories for docinsight.json. It uses the nearest manifest it finds:

shell
docinsight check
docinsight build

This lets commands run from the project root or from a documentation or source subdirectory.

Discovery follows the directory hierarchy, so a command started outside the project root cannot find that project's manifest automatically. Sources outside the project root remain valid inputs, but run commands from within the project or use --manifest to select the project explicitly.

If DocInsight does not find docinsight.json, it uses a single legacy .diproj manifest in the current directory. When the directory contains more than one .diproj file, select one explicitly.

Specify a manifest

Use --manifest to point a command at a specific docinsight.json or legacy .diproj manifest:

shell
docinsight check --manifest products/mylibrary/docinsight.json
docinsight build --manifest ../product-docs/docinsight.json

A relative --manifest path is resolved from the current working directory. Explicit selection is useful in scripts, CI jobs, monorepos, and repository layouts where documentation and source code live in different locations.

Manifest selection identifies the project; it does not choose which configured outputs a command uses. For that behavior, see Select output targets.


Select output targets | DocInsight Docs

  1. Guide
  2. Check, build, and automate

Select output targets

On this page

  1. Use the default targets
  2. Select named targets
  3. Override target output paths
  4. Select all targets
  5. Select targets by format
  6. Select legacy output formats

The check, build, open, and clean commands operate on selected output targets. Use the manifest defaults for routine work, or select named targets and override their output paths from the command line.

Use the default targets

When a command does not pass a target selection option, DocInsight uses output.default_targets from the manifest. If default_targets is omitted, DocInsight selects all configured output targets.

Default targets keep routine check, build, and clean commands short while allowing other targets to remain available when needed.

Select named targets

Use --target to select a named output target from docinsight.json:

shell
docinsight build --target site
docinsight open --target site
docinsight clean --target site

Use target selection when a project builds multiple outputs, or when open should open one specific generated output.

Repeat --target to select more than one named target:

shell
docinsight build --target site --target help

Override target output paths

Append =PATH to a target name to replace its configured output path for one command:

shell
docinsight build --target site=dist/site
docinsight build --target "site=dist/my site"

Quote the complete NAME=PATH argument when the path contains spaces. A relative override path is resolved from the current working directory, not from the directory containing docinsight.json.

Repeat --target to override multiple targets in the same command:

shell
docinsight build --target site=dist/site --target help=dist/help.chm

Overridden and configured output paths can also be used together:

shell
docinsight build --target site=dist/site --target help

Each NAME=PATH value overrides only its named target. A selected target without =PATH continues to use the path configured in the manifest. Overrides change only the effective output locations for that command; they do not update target paths in the manifest.

The same syntax works with check, build, open, and clean:

shell
docinsight check --target site=dist/site
docinsight open --target site=dist/site
docinsight clean --target site=dist/site

check validates the effective output locations without writing generated output. When you build to override paths, pass the same overrides to clean to operate on those outputs. The open command, and build --open, require exactly one selected target.

For shared team manifests, keep the configured target path local and excluded from version control. Use an override only when a publishing command intentionally writes to a shared or deployment location. See Keep team output local.

Select all targets

Use --all-targets with check, build, or clean to ignore output.default_targets and select every configured output target:

shell
docinsight check --all-targets
docinsight build --all-targets
docinsight clean --all-targets

Select targets by format

Use --format to select every configured target with a particular output format:

shell
docinsight build --format html
docinsight clean --format chm

The supported values are html and chm. Because open requires exactly one target, use --format with open only when exactly one configured target has that format.

--target, --all-targets, and --format are mutually exclusive selection methods.

Select legacy output formats

Legacy .diproj manifests do not define named output targets. Use --format html or --format chm with build. The legacy open command requires one of these format selections:

shell
docinsight build --manifest MyLibrary.diproj --format html
docinsight open --manifest MyLibrary.diproj --format html

check does not support target selection for legacy manifests, and clean does not support legacy manifests.


Automate CLI workflows | DocInsight Docs

  1. Guide
  2. Check, build, and automate

Automate CLI workflows

On this page

  1. Run commands non-interactively
  2. Check documentation changes
  3. Build documentation output
  4. Clean output safely
  5. Accept the trial license agreement
  6. Preserve diagnostic logs

Use the same DocInsight commands in local scripts and continuous integration jobs. Make the project context explicit and disable interactive behavior so that a job does not depend on its working directory or wait for user input.

Run commands non-interactively

Pass --no-input when a command must never prompt. Disable terminal features when the CI log consumer does not process ANSI colors, progress indicators, or hyperlinks:

shell
docinsight check --manifest docinsight.json --no-input --no-color --no-progress --no-hyperlinks

Activate DocInsight in the automation environment before running commands that require a license. See Activate DocInsight.

Check documentation changes

Run check as the default validation step for documentation changes:

shell
docinsight check --manifest docinsight.json --all-targets --no-input --no-color

A failed check returns a nonzero exit status, allowing the job to fail without parsing human-readable output.

Build documentation output

Use build when the job should produce generated documentation. Select a named target when the manifest defines more than one output:

shell
docinsight build --manifest docinsight.json --target site --no-input --no-color

Keep each manifest target path local and excluded from version control. If a publishing job intentionally writes directly to a shared or deployment location, override the path for that invocation:

shell
docinsight build --manifest docinsight.json --target site=Z:/docs/mylibrary --no-input --no-color

For override path resolution and the corresponding open and clean commands, see Override target output paths.

DocInsight does not provide a separate publish command. Build directly to a controlled deployment location with an override, or use your deployment or packaging tool to publish the generated directory or file after a successful build.

Use --dry-run to verify target selection and the build plan without writing generated output:

shell
docinsight build --manifest docinsight.json --target site --dry-run --no-input --no-color

Clean output safely

Review a clean operation before allowing automation to delete generated files:

shell
docinsight clean --manifest docinsight.json --all-targets --dry-run --no-input --no-color

Remove --dry-run only when the selected manifest and targets are correct.

Accept the trial license agreement

Non-interactive builds that use a trial license require explicit acceptance:

shell
docinsight build --accept-license --no-input

Use --accept-license only when the automation environment is allowed to accept the trial license agreement.

Preserve diagnostic logs

Use --log-file to retain detailed diagnostics as a job artifact. Set --log-level when the default file log level does not contain enough detail:

shell
docinsight build --manifest docinsight.json --target site --no-input --no-color --log-file artifacts/docinsight.log --log-level debug

Use --quiet only when the job needs to suppress normal progress and summaries. Warnings and errors remain visible.

For exact command and option syntax, see the generated CLI command reference.


Control console output and logs | DocInsight Docs

  1. Guide
  2. Check, build, and automate

Control console output and logs

On this page

  1. Choose terminal verbosity
  2. Control terminal presentation
  3. Write a log file
  4. Troubleshoot build failures

DocInsight separates human-readable terminal output from diagnostic log files. Adjust terminal output for interactive or automated use, and create a log file when investigating a failure or preparing a support request.

Choose terminal verbosity

By default, commands show normal progress, warnings, and errors. Use --quiet when only warnings and errors should be printed:

shell
docinsight check --quiet

Use -v to print more detail. Repeat it for more verbose output:

shell
docinsight build -v
docinsight build -vv

Control terminal presentation

DocInsight normally selects color behavior for the current terminal. Use --color to choose auto, always, or never, or use --no-color as a shortcut for disabling color:

shell
docinsight check --color always
docinsight check --no-color

Progress indicators and file hyperlinks also default to auto. Override automatic detection when a terminal or log consumer needs deterministic output:

shell
docinsight build --progress never --hyperlinks never

--no-progress and --no-hyperlinks are shortcuts for disabling these features.

Write a log file

Use --log-file to append diagnostic logs to a file. DocInsight creates missing parent directories:

shell
docinsight build --log-file logs/docinsight.log

Set --log-level to control the minimum diagnostic logging level:

shell
docinsight build --log-file logs/docinsight.log --log-level debug

When you pass --log-level, DocInsight also writes diagnostic log events at that level to stderr. The same level applies to --log-file when both options are present.

The same settings can be provided with environment variables. In PowerShell:

powershell
$env:DOCINSIGHT_LOG_FILE = "logs/docinsight.log"
$env:DOCINSIGHT_LOG_LEVEL = "debug"
docinsight build

Terminal verbosity and diagnostic logging are separate controls. --quiet suppresses normal progress and summaries, but it does not disable diagnostic logging requested with --log-level.

Troubleshoot build failures

Build diagnostics can come from manifest resolution, content ingestion, source analysis, target generation, or an external tool. Run check first, then capture a detailed build log:

shell
docinsight check --all-targets
docinsight build --target site --log-file logs/docinsight-build.log --log-level debug

For CHM compiler failures, verify that Microsoft HTML Help Workshop is installed. If hhc.exe is in a nonstandard location, set DOCINSIGHT_HHC_TOOL to its full path.

For exact console and logging options, see the command pages in the generated CLI command reference.


Delphi IDE extension overview | DocInsight Docs

  1. Guide
  2. Delphi IDE extension

Delphi IDE extension overview

The DocInsight Delphi IDE extension adds documentation authoring, checking, and building tools to Delphi. The extension works with XML documentation comments in Delphi source; the CLI uses the same comments when it checks and builds Delphi API reference content.

After installation, Delphi displays a top-level DocInsight menu.

DocInsight menu and Tools submenu in the Delphi IDE

Use the menu commands to:

  • Inspect and edit the declaration at the source-editor caret with Documentation Inspector.

  • Browse source structure and rendered comments with Documentation Explorer.

  • Check XML documentation comments or build a documentation project.

  • Configure extension options and manage your license.

If the DocInsight menu is missing, see Get support.


Documentation Inspector | DocInsight Docs

  1. Guide
  2. Delphi IDE extension

Documentation Inspector

On this page

  1. Preview documentation
  2. Edit documentation visually

Use DocInsight > Documentation Inspector to open a dockable documentation window synchronized with the Delphi source editor. It works with the declaration at the current caret position and provides separate Preview and Design modes.

Documentation Inspector editing the IList.Insert method in Delphi

Preview documentation

Use Preview to see the generated API documentation for the current unit, type, method, property, or other declaration. The preview combines information from the declaration with its XML documentation comment.

Follow documentation links to move between related symbols, use Back and Forward to navigate the history, and use Go to Declaration to return to the corresponding location in the source editor.

Edit documentation visually

Use Design as a WYSIWYG editor for summaries, parameters, return values, remarks, and other documentation sections. The formatting toolbar supports bold, italic, underline, strikethrough, inline code, bulleted and numbered lists, links, tables, images, and code blocks.

DocInsight converts visual edits to well-formed XML documentation and updates the comment associated with the declaration in Delphi source. For common documentation, you do not need to edit the XML markup by hand.

The visual editor does not currently provide a dedicated Xref target picker. To author an xref link, select Insert link > URI and enter an xref: URI, such as xref:docs/collections. You can also add the corresponding xref attribute directly in the Delphi source editor; see Link API symbols and topics.

After editing comments, check documentation in the IDE to find XML documentation problems in the selected source scope. Run docinsight check when you also need to check the configured documentation project.


Documentation Explorer | DocInsight Docs

  1. Guide
  2. Delphi IDE extension

Documentation Explorer

Use DocInsight > Documentation Explorer to browse the current project, unit, type, and member structure and preview or edit the selected declaration's documentation.

Documentation Explorer showing the IList interface and its generated documentation

Select an item in the structure tree to display its rendered documentation. Follow documentation links or use the navigation history to move among related symbols, and use Go to Declaration to return to a declaration in the source editor.

Use Documentation Explorer with Documentation Inspector when you need to move through several related declarations and update their comments in one editing session.


Check documentation in the IDE | DocInsight Docs

  1. Guide
  2. Delphi IDE extension

Check documentation in the IDE

Use DocInsight > Check Documentation... to find XML documentation problems without leaving Delphi.

  1. Choose DocInsight > Check Documentation....

  2. Select Current File, Open Files, Active Project, or Project Group under Scope.

  3. Choose OK.

DocInsight reports diagnostics for the selected source scope, including malformed XML documentation comments and unresolved symbol references.

To check a configured documentation project or run checks in CI, use the CLI:

shell
docinsight check

For CLI checking workflows, see Check documentation.


Build documentation in the IDE | DocInsight Docs

  1. Guide
  2. Delphi IDE extension

Build documentation in the IDE

Use DocInsight > Build Documentation... to open the Documentation Project Wizard for the current Delphi project group, or for the active project when no saved project group is available.

If a matching .diproj documentation project does not exist, the wizard creates one and imports the active Delphi project or project group. Review the source and output settings, and then choose Build. The wizard saves the .diproj file, runs the DocInsight CLI in a command prompt, and opens the generated output after a successful build.

To build a docinsight.json project directly or automate a build, see Build documentation.


Configure the IDE extension | DocInsight Docs

  1. Guide
  2. Delphi IDE extension

Configure the IDE extension

On this page

  1. Use extension tools

Use DocInsight > Options... to open the DocInsight pages in Delphi's options dialog.

The Shortcuts page configures keyboard shortcuts for Documentation Inspector, Documentation Explorer, Build Documentation, Check Documentation, Format Documentation, Fold Documentation, and Unfold Documentation.

The Update page controls Check for updates automatically and Download updates automatically. To check manually, choose DocInsight > Check for Updates....

Use extension tools

The DocInsight > Tools menu contains commands for working with and diagnosing the extension:

  • DocInsight Command Prompt opens a command prompt in the active project's directory. If no project is active, it opens in the DocInsight installation directory.

  • Restart DocInsight Server restarts the local service used by the IDE extension.

  • Debug Logging turns debug logging on or off and restarts the service to apply the change.

  • Show Logs opens the extension's log directory.

Turn on Debug Logging, reproduce a problem, and then use Show Logs when support asks for an extension log. Logs can contain local paths, project details, source excerpts, or documentation content; review them before sharing.


Manage licenses in the IDE | DocInsight Docs

  1. Guide
  2. Delphi IDE extension

Manage licenses in the IDE

Use DocInsight > License... to view or update DocInsight license information from the Delphi IDE.

Show the same license information from the CLI:

shell
docinsight license show

For CLI license workflows, see Manage licenses.

For activation problems, see Get support.


Delphi extension compatibility | DocInsight Docs

  1. Guide
  2. Delphi IDE extension

Delphi extension compatibility

During installation, DocInsight registers the architecture-appropriate DocInsightLoader.dll as an IDE expert for each Delphi version you select. When bds.exe starts, the loader detects the running BDS version and loads the matching version-specific extension DLL from the active toolchain. The following table lists the extension DLL selected at runtime for each supported version.

DocInsight DLL | Delphi version | BDS version | IDE architecture
DocInsight370.dll | Delphi 13 Florence | 37.0 | x86 and x64
DocInsight290.dll | Delphi 12 Athens | 23.0 | x86 and x64
DocInsight280.dll | Delphi 11 Alexandria | 22.0 | x86
DocInsight270.dll | Delphi 10.4 Sydney | 21.0 | x86
DocInsight260.dll | Delphi 10.3 Rio | 20.0 | x86
DocInsight250.dll | Delphi 10.2 Tokyo | 19.0 | x86
DocInsight240.dll | Delphi 10.1 Berlin | 18.0 | x86
DocInsight230.dll | Delphi 10 Seattle | 17.0 | x86
DocInsight220.dll | Delphi XE8 | 16.0 | x86
DocInsight210.dll | Delphi XE7 | 15.0 | x86

You normally do not need to select or register a version-specific DLL manually. List the Delphi installations detected by DocInsight and their extension status:

shell
docinsight delphi list

Enable the loader for every detected installation:

shell
docinsight delphi enable

The DocInsight installer also enables the loader for the Delphi versions you select during installation.


Markdown path compatibility | DocInsight Docs

  1. Guide
  2. Reference

Markdown path compatibility

On this page

  1. Relative paths
  2. Root-relative paths
  3. GitHub and VS Code compatibility
  4. Configure the reference root
  5. Other authored paths

DocInsight resolves authored paths before it generates output URLs. Relative paths provide the most portable behavior across DocInsight, GitHub, and Visual Studio Code. Use a root-relative path when the path should start from a stable project or repository location.

Relative paths

A relative path starts from the directory that contains the Markdown file:

markdown
See [Installation](../getting-started/installation.md).

![Options dialog](images/options.png)

A relative path first resolves from the source file within its Markdown content entry. A local topic is resolved in that entry, and a local resource is copied with it when referenced. If the normalized path is not owned there, it may resolve through project.reference_root to another declared content owner or, for a resource, a project asset set. The output target must select the resolved owner.

Root-relative paths

A root-relative path begins with / and is resolved against project.reference_root. It is not an operating-system absolute path or a generated site URL.

The reference root defaults to the DocInsight project root. For this project layout:

text
my-library/
|-- docinsight.json
|-- docs/
|   `-- getting-started/
|       `-- installation.md
`-- images/
    `-- logo.svg

Markdown can refer to the topic and image by their paths from the project root:

markdown
See [Installation](/docs/getting-started/installation.md).

![Logo](/images/logo.svg)

DocInsight resolves the source path and its declared owner before it determines how to publish the target. A topic must be publishable content owned by the current project. A resource can belong to a Markdown content entry or a project asset set. The output target must select that owner, whose content binding or asset mount determines the published path. See Assets for ownership and selection rules.

GitHub and VS Code compatibility

The same Markdown path syntax uses different configured roots across authoring tools:

Path form | DocInsight | GitHub | VS Code
name, ./name, or ../name | Directory containing the Markdown file | Directory containing the Markdown file | Directory containing the Markdown file
/name | Configured project.reference_root | Repository root | Current workspace root

GitHub documents both file-relative and root-relative paths in Relative links and image paths in Markdown files. VS Code documents the corresponding editor behavior in Markdown path completions.

Prefer relative paths for nearby topics and resources. They keep the same meaning when a project directory moves or when a different folder is opened as the VS Code workspace.

Root-relative paths work consistently only when the DocInsight reference root, GitHub repository root, and VS Code workspace root identify the same directory. This is common for a standalone project. A monorepo requires additional configuration.

Configure the reference root

When docinsight.json is at the repository root, omit project.reference_root. Its default value, ., already makes the DocInsight reference root match the GitHub repository root.

In a monorepo, the DocInsight project root is usually below the repository root:

text
repository/
|-- products/
|   `-- my-library/
|       |-- docinsight.json
|       |-- docs/
|       |   `-- getting-started/
|       |       `-- installation.md
|       `-- images/
|           `-- logo.svg
`-- shared/

With the default reference root, /docs/getting-started/installation.md works in DocInsight but points at repository/docs/ on GitHub. To make the three tools use the repository root, set project.reference_root to ../.. and open repository/ as the VS Code workspace.

The property must resolve to the DocInsight project root or one of its ancestor directories. Its value is relative to the directory containing docinsight.json:

json
{
  "project": {
    "name": "my-library",
    "reference_root": "../.."
  }
}

To set the value during initialization, use --reference-root; see the init command reference.

Root-relative paths must then include the project directory from the repository root:

markdown
See [Installation](/products/my-library/docs/getting-started/installation.md).

![Logo](/products/my-library/images/logo.svg)

The common layouts are:

Layout | project.reference_root | Topic path
docinsight.json at repository root | Omit or use . | /docs/getting-started/installation.md
products/my-library/docinsight.json in a monorepo | ../.. | /products/my-library/docs/getting-started/installation.md

project.reference_root affects only root-relative paths. It does not change:

  • Relative Markdown paths.

  • Manifest paths such as content roots, asset roots, or output paths.

  • Content or asset ownership.

  • Generated mounts, routes, or public URLs.

A topic or resource must still belong to the current DocInsight project; a path to a sibling project is not supported.

If contributors may open different subdirectories as their VS Code workspace, prefer relative paths instead of relying on /.

Other authored paths

Include and snippet sources must use relative paths and remain inside their Markdown content root. Delphi XML documentation resolves local resources relative to the .pas source file and does not currently support root-relative paths.

External URLs retain their normal URL semantics and are not resolved from the reference root.


DocInsight manifest reference | DocInsight Docs

  1. Guide
  2. Reference

DocInsight manifest reference

On this page

  1. File format
  2. Top-level structure
  3. Names and references
  4. Paths, mounts, and glob patterns
    1. Mount paths
    2. Glob patterns
  5. Variables
  6. Properties
    1. $schema
    2. edition
    3. requires
    4. project
    5. variables
    6. sources
      1. Delphi source
    7. content
      1. Markdown content
      2. Delphi content
    8. assets
    9. i18n
    10. site
    11. sites
    12. output
      1. HTML target
      2. CHM target
  7. Validation and compatibility
  8. Important defaults

This page describes the public docinsight.json format for manifest edition 2026, including its fields, defaults, paths, patterns, and variable syntax.

File format

A manifest is a UTF-8 JSONC document whose root value is an object. Its conventional file name is docinsight.json.

Line comments, block comments, and trailing commas are allowed. Property names and string values use double quotes. An initial UTF-8 byte order mark (BOM) is ignored.

JSON null values and duplicate property names are not allowed. To leave an optional property unspecified, omit it.

The root object must declare a project object.

Top-level structure

Property | Value | Purpose
$schema | string | JSON Schema URI for editor integration
edition | string | Manifest edition
requires | object | Required manifest features
project | object | Project identity and metadata
variables | object | User-defined variables
sources | named collection | Shared source contexts
content | named collection | Publishable content
assets | named collection | Files copied to selected outputs
i18n | object | Internationalization defaults
site | object | Default site definition
sites | named collection | Named replacement site definitions
output | object | Output targets and default selection

Only documented properties are accepted, except for keys inside named collections and variable objects. Property names are case-sensitive.

An empty string, object, or array is an authored value, not an omitted value. Individual fields may reject empty values or give them a specific meaning.

Names and references

In a project manifest, project, source, content, asset-set, site, and output-target names are entity names. An entity name contains 1–64 ASCII letters, digits, underscores, or internal hyphens. It must contain at least one letter or digit; a hyphen cannot appear first, last, or twice in succession.

Valid names include docs, DocsAPI, docs_api, docs-api, 2026, and _internal. Invalid names include _, -docs, docs-, docs--api, and 文档.

Spelling is preserved, while lookup is ASCII case-insensitive. Thus Guide and guide identify the same entity, but guide-api and guide_api are different names.

The sources, content, assets, sites, and output.targets objects are named collections. Names must be unique within each collection. References use the same case-insensitive lookup:

  • content.<name>.source references sources;

  • output.targets.<name>.content references content;

  • output.targets.<name>.assets references project asset sets;

  • a string-valued output.targets.<name>.site references sites;

  • output.default_targets references output.targets.

These references use exact names rather than wildcard patterns.

Paths, mounts, and glob patterns

Relative filesystem paths are resolved from the directory containing docinsight.json.

Value | Resolution
project.reference_root | Manifest-relative project root or real ancestor; defaults to .
Markdown root | Manifest-relative directory that must remain inside the manifest directory
Asset-set root | Manifest-relative directory that must remain inside the manifest directory
Delphi source root | Manifest-relative directory that must remain inside the manifest directory
Output target path | Optional manifest-relative or absolute default output path
site.base_path or sites.<name>.base_path | URL path beginning with /; defaults to /

Markdown, asset, and Delphi source roots cannot be absolute, contain a parent (..) component, or leave the manifest directory. No filesystem redirection is followed from the project directory to a root or through selected input; this includes symbolic links, junctions, and other reparse points. The reference root is the explicit exception to the parent-path rule: it may contain .., but it must canonicalize to the project root or one of its real ancestors. Output paths may resolve outside the manifest directory.

Configured output paths, mount paths, and URL paths use /. They do not expand {{...}} variable references or platform-style environment variables.

Mount paths

content.<name>.mount and assets.<name>.mount are logical paths below an output root. An optional leading / is ignored, and / selects the output root.

When mount is omitted, it defaults to the declared content or asset-set name with its original spelling. For example, content named APIReference mounts at APIReference, not api-reference. Set an explicit mount when the published path must remain stable across renames.

Mounts use non-empty ASCII segments separated by /. A segment may contain letters, digits, underscores, single internal hyphens, and single dots between non-empty parts. One leading dot is allowed. Empty segments, ., .., leading or trailing hyphens, repeated hyphens, and repeated dots are invalid.

Glob patterns

files and exclude contain case-insensitive glob patterns relative to the associated root:

  • / is the logical separator; input backslashes are normalized to /;

  • a leading / anchors a pattern to the root;

  • a trailing / selects a directory subtree;

  • an exclusion without / matches that file name at any depth;

  • parent (..) components are not allowed;

  • exclusions take precedence over inclusions.

Variables

A variable identifier contains 1–64 ASCII bytes. It starts with a letter and continues with letters, digits, or underscores. Examples include product, ProductName, and product_2; 2product, _product, and product-name are invalid.

Identifier spelling is preserved and lookup is ASCII case-insensitive. Every segment of a dotted variable path follows the same rule.

Variable references use {{name}} or dotted {{object.field}} syntax. Whitespace immediately inside the braces is ignored. Unknown paths, cycles, and attempts to render an object directly are errors.

User variables may be:

  • strings, which may contain variable references;

  • links, written as { "type": "link", "label": "...", "href": "..." };

  • objects, written directly as fields or as { "type": "object", "fields": { ... } }.

Link labels and targets are literal and do not expand variables. Link targets may be relative references or use the http, https, mailto, or tel scheme.

Reserved variable names include:

text
sys workspace project site target content topic page api

project exposes name, title, description, homepage, repository, license, and copyright. The value of project.name does not define an additional variable, even when it is a valid variable identifier.

sys.docinsight is the built-in DocInsight link and exposes label and href.

Manifest variables expand in user string variables, site.title, site.title_suffix, site.description, site.footer.notice, and the corresponding fields under sites.<name>. Project metadata is literal.

Properties

Unless a property is marked required, it is optional.

$schema

Optional string containing a JSON Schema URI for editor integration. DocInsight does not currently publish an official Schema URI, so this property can be omitted. It does not select the manifest edition.

edition

String. The supported value is "2026". When omitted, it defaults to "2026".

Writers should include the edition explicitly so the manifest's intended contract is clear.

requires

Compatibility object.

Property | Value | Default
features | array of unique lowercase kebab-case feature IDs, each 1–64 ASCII bytes | []

The current toolchain supports no optional feature IDs, so a non-empty features array is rejected.

project

Required object containing the project identity and metadata.

Property | Value | Required
name | entity name | yes
reference_root | relative filesystem path to the project root or an ancestor | no; default .
title | string | no
description | string | no
homepage | href string or link object | no
repository | href string or link object | no
license | label string or link object | no
copyright | string | no

A project link object requires a non-blank href and literal label. String-form homepage and repository values receive default labels. A license link object likewise requires both a non-blank label and href.

Root-relative paths begin with / and resolve against project.reference_root. The property is resolved from the directory containing docinsight.json and must resolve to a real directory that contains the current project root. DocInsight canonicalizes symbolic links, does not inspect Git, and does not treat the reference root as permission to reference a sibling DocInsight project.

variables

Object keyed by variable identifiers. Object field names use the same identifier rules. Missing and {} both define no user variables.

json
{
  "variables": {
    "company": {
      "name": "DevJet Software",
      "homepage": {
        "type": "link",
        "label": "DevJet Software",
        "href": "https://devjetsoftware.com/"
      }
    },
    "product": "{{project.title}}"
  }
}

sources

Named collection of shared source contexts. The supported source type is delphi.

Delphi source

Property | Value | Required or default
type | "delphi" | required
root | filesystem path | .
files | non-empty array of project-file globs | required
exclude | array of exclusion globs | []
xref | source namespace and project overrides | defaults below
options | Delphi analysis options | required

Project discovery accepts .groupproj, .dproj, .dpr, and .dpk files.

files and exclude form a file scope relative to root. exclude filters only project and project-group entries matched directly by files; it is not reapplied to projects or units reached while expanding the selected graph. Project, unit, and symbol publication filtering belongs to Delphi content.

Property | Value | Default
xref.namespace | Xref namespace for the source | project.name
xref.projects | exact project-name-to-namespace object | {}

The effective Xref namespace for a Delphi project is selected in this order: an exact xref.projects mapping, xref.namespace, then the manifest's project.name. Effective namespaces are normalized to lowercase. xref.projects keys are case-insensitive .dproj filename stems and do not accept wildcard patterns; each value is a complete namespace. For example:

json
{
  "xref": {
    "projects": {
      "MyLibrary.Tests": "mylibrary.tests"
    }
  }
}

This maps the Delphi project MyLibrary.Tests to mylibrary.tests; projects without an override use project.name when xref.namespace is omitted. The source filesystem root does not affect Xref namespaces.

The namespace is the first segment of every Delphi Xref. The Delphi content name and mount do not affect it, so content named api still exports an Xref such as mylibrary/MyLibrary.Collections/IList{T}, not api/.... Package local IDs start at the fully qualified unit name. Program and library local IDs start with the Delphi project name, so MyLibrary.Tests under the default namespace may produce mylibrary/mylibrary.tests/.... An exact project override to mylibrary.tests removes the repeated project segment and produces mylibrary.tests/.... A source-wide xref.namespace does not remove it.

options contains:

Property | Value | Required or default
compiler | Delphi compiler ID | required
environment | local or custom environment object | local x86
platform | platform string | required for multi-platform compilers; otherwise Win32
config | configuration string | toolchain default
defines | array of conditional symbols | []
properties | string-valued property object | {}

Compiler IDs are delphi_2007, delphi_2009, delphi_2010, delphi_xe through delphi_xe8, delphi_10 through delphi_10_4, delphi_11, delphi_12, and delphi_13.

Set platform explicitly when the selected compiler supports more than Win32. Compilers that support only Win32 default to Win32 when it is omitted.

A local environment uses "type": "local" and accepts arch ("x86" or "x64") and registry_root. A custom environment uses "type": "custom" and accepts string-valued variables and search_paths. The property names Platform, Config, and Configuration are reserved in options.properties, case-insensitively.

content

Named collection of publishable content. Every content entry has:

Property | Value | Required or default
type | "markdown" or "delphi" | required
title | display string | content name
mount | mount path | content name

Markdown content

Property | Value | Required or default
root | manifest-relative directory | required
files | non-empty array of globs | ["**/*.md"]
exclude | array of exclusion globs | []

root defines the entry's Markdown source path space and the containment boundary for includes, snippets, and content-local assets. files and exclude select the .md source files that belong to the entry as topic candidates. They are membership filters, not a security boundary and not a guarantee that every candidate is published. Draft filtering, toc.md navigation, and output-target selection determine later publication.

Markdown content entries may share or overlap a root; the content entry name, not the directory, is the content and Xref namespace. After resolving roots and enumerating the actual file scopes, one physical Markdown topic source may belong to only one content entry across the project. This is validated before draft, TOC-publication, or target-selection filtering. A toc.md is navigation source rather than a topic and may be read by more than one entry.

Files inside root that are not selected as topics may still be referenced explicitly as include fragments, snippet sources, or content-local assets. Such dependencies may be shared by multiple content entries, are not topics merely because they are inside root, and are not published as topics automatically. Use separate roots, rather than files or exclude, when content must have a different filesystem containment boundary.

A relative Markdown topic link first resolves to a topic owned by the current content entry. If no local topic matches, the path may resolve from the containing file to a topic owned by another content entry. Root-relative topic links may also cross content entries. Every output target that includes the source content must include the destination content; otherwise check and build report an unpublished topic dependency. Xrefs remain useful when semantic IDs are more stable than physical source paths.

Relative and root-relative image or file links may likewise bind to a local asset below another Markdown content's root. The asset is published below the destination content's mount, and every target that includes the source content must also include that destination content. Paths outside all Markdown content roots remain invalid; rooted project assets continue to require a selected project asset set.

Only toc.md directly under root is the content's root TOC. When there is no root TOC, a root-level index.md is preferred as the default topic, followed by the first publishable topic. If exactly one topic is publishable, it is treated as a single-page landing topic wherever it is located and whatever it is named. For example, root: "docs" with files: ["release-notes/2026.1/index.md"] is supported without moving the content root.

Each Markdown topic has an ID local to its content entry. By default, the ID is the topic's root-relative source path without the .md extension. A topic may override it with the front matter id property:

markdown
---
id: getting-started
---

# Getting started

The ID supplies the topic's local Xref identity and conventional output route. It must be unique within one content entry; different content entries may use the same ID because the content entry name supplies the namespace. The front matter property is id; name is not a compatibility alias.

A Markdown topic may also configure its document-local Xref scope with front matter xref:

markdown
---
xref:
  base: mylibrary/MyLibrary.Collections
  aliases:
    list: mylibrary/MyLibrary.Collections/IList{T}
---

Both base and aliases are optional. base installs the document's default binding; aliases maps local names to absolute Xref bindings. For address forms and lookup order, see Configure a document Xref scope.

Delphi content

Property | Value | Required or default
source | Delphi source name | required
filter | declaration filter object | defaults below
reference | reference-page options | defaults below
structure | TOC and path options | defaults below
Property | Values | Default
filter.xref_namespaces | name filter object | all namespaces
filter.projects | name filter object | all projects
filter.units | name filter object | all units
filter.symbols | name filter object | all symbols
filter.sections.implementation | boolean | false
filter.visibility.private | boolean | false
filter.visibility.strict_private | boolean | follows private
filter.visibility.protected | boolean | true
filter.visibility.strict_protected | boolean | follows protected
reference.inherited_members | "none", "linked" | "linked"
structure.toc.scope | "unified", "project", "unit" | "project"
structure.path.project | "none", "auto", "always" | "auto"

Public, published, and automated declarations are always included.

Each semantic name filter accepts a non-empty include array, a non-empty exclude array, or both. An omitted filter or omitted include selects all names in that dimension. exclude is applied after include, so exclusion wins when both match. Patterns are case-insensitive, whole-name wildcard patterns: * matches zero or more characters and ? matches exactly one. They are not filesystem globs; . is an ordinary character, * can match across it, and / and \\ are invalid.

xref_namespaces matches each project's effective Xref namespace, projects matches its .dproj filename stem, units matches the declared fully qualified unit name, and symbols matches the unit-qualified symbol name without parameter types or an overload signature. All applicable dimensions must match for a declaration to be published.

For example, this content publishes selected projects while excluding internal units and deprecated symbols:

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

assets

Named collection of project asset sets. Assets are published into each output target that explicitly selects the set. Defining a set does not change any target's output.

Property | Value | Required or default
root | manifest-relative directory | . (the manifest directory)
files | non-empty array of globs | required
exclude | array of exclusion globs | []
mount | mount path | asset-set name

files is the positive publication allowlist. DocInsight never treats an omitted files property as ["**/*"]; to publish the complete root, write "files": ["**/*"] explicitly. exclude filters the allowlist and is not a security boundary. The root is only the resolution boundary for patterns and relative paths.

Only regular files that remain inside the resolved root are published. Missing exact files, invalid patterns, path traversal, filesystem redirection, and patterns with no publishable matches fail validation. Redirection includes symbolic links, junctions, and other reparse points, even when the destination remains inside the root. Published paths retain their path relative to root below mount.

Markdown references a project asset by a root-relative path, for example /project1/assets/images/logo.svg. Asset-set names are not part of authored URLs. For each target, the physical file must match exactly one selected set, unless multiple matches provably produce the same artifact identity. Query strings and fragments do not participate in source lookup.

Delphi XML documentation does not use project asset sets for local links. Its local files are relative to the containing .pas file and must remain inside the declared Delphi source root.

The former property name resources is not accepted as an alias.

i18n

Internationalization object.

Property | Value | Default
default_locale | locale string | "en-US"

An empty or whitespace-only default_locale also resolves to "en-US".

site

Default site definition inherited by site-aware HTML and CHM targets whose target-local site property is omitted. When this definition is absent, those targets have no selected site definition and still derive rendered values such as title and description from project metadata.

Property | Value | Default
title | interpolated string | project title, then project name
title_suffix | interpolated string | resolved site title prefixed by a space-pipe-space separator
description | interpolated string | project description
origin | HTTP(S) origin | none
base_path | absolute URL path | /
favicon | published .ico, .svg, or .png asset path | Web output reuses favicon.ico or supplies a built-in icon
robots | robots meta content | none
footer.notice | interpolated string | none

origin contains only an HTTP or HTTPS origin: no user information, path, query, or fragment. base_path begins with one /; a trailing / is added when needed.

A configured favicon must name a file published by one of the project asset sets explicitly selected by the current target. A favicon never auto-selects an asset set.

sites

Named collection of alternative site definitions. Each value has the same shape as site. A target selects one by name with its target-local site property.

A named site is a full replacement for the top-level default site. DocInsight does not merge site with sites.<name>, does not implicitly select the sole named site, and does not treat any site name as special.

json
{
  "project": { "name": "docs" },
  "site": { "title": "Documentation" },
  "sites": {
    "offline": { "title": "Offline Help" }
  },
  "output": {
    "targets": {
      "site": {
        "type": "html",
        "path": "dist/site",
        "content": ["guide"]
      },
      "help": {
        "type": "chm",
        "path": "dist/help.chm",
        "site": "offline",
        "content": ["guide"]
      }
    }
  }
}

output

Output configuration.

Property | Value | Default
default_targets | non-empty array of target names | all targets in canonical identity order
targets | named target collection | {}

docinsight init names its generated HTML target site and places it at dist/docs/site. Target names are not reserved, and URL behavior remains explicitly configured on each target.

Each target contains:

Property | Value | Required
type | "html" or "chm" | yes
path | literal default filesystem path | no; require an external binding when selected
site | false, true, or site name | no; inherit top-level site
canonical | false, true, or { "target": name } | no; defaults to false
content | non-empty ordered array of content bindings | yes
assets | non-empty array of project asset-set names | no; publish no project asset sets

For HTML and CHM targets, omitting site or setting it to true selects the top-level default. Setting it to false disables site selection. A site name selects sites.<name> as a full replacement. A target without a selected site definition still receives normal renderer-derived values from project metadata. Inline site objects are invalid.

Canonical links are disabled by default. Set canonical to true to use the current target's routes, URL settings, and selected site. Use { "target": "name" } to use another declared target as the canonical URL source; the referenced target must exist. Set it to false to disable them.

Target content, asset-set, and named-site references must exist. Content and asset-set references cannot contain duplicates or wildcards. Omitting assets publishes no project asset sets; references in selected content do not auto-select a set. Content-local assets remain internal dependencies of selected content and do not appear in this array.

A selected asset set publishes every file matched by its files and exclude patterns.

A target content binding is either an exact content-name string or an object with name and an optional target-specific mount projection. String and object bindings may be mixed while retaining array order:

json
{
  "content": [
    "api",
    {
      "name": "docs",
      "mount": {
        "/release-notes/": "/release-notes/2026.1",
        "/": "/2026.1"
      }
    }
  ]
}

"docs" and { "name": "docs" } are equivalent and inherit content.docs.mount. A binding's optional mount accepts either:

  • a string replacing the complete content mount for this target; or

  • an object mapping content-local rooted directory prefixes to target mounts.

"mount": "/2026.1" is equivalent to "mount": { "/": "/2026.1" }. A mount projection object must be nonempty and include / as its complete fallback. Matching uses the longest path-segment prefix, consumes that prefix, and does not depend on JSON property order. Source keys are / or rooted directory prefixes; /release-notes and /release-notes/ are equivalent. They reject empty, ., .., and backslash-separated segments, and equivalent spellings cannot both be declared. Destination values use the ordinary mount grammar with an optional trailing /; / selects the target root.

The projection applies equally to topics and content-owned assets. A cross-content local asset uses the binding of the content that owns the asset. Project asset sets retain their own assets.<name>.mount. Mount projection is resolved before HTML/CHM artifact and URL encoding; site.base_path and clean URL behavior are applied later.

HTML target

An HTML target path is a directory. It also accepts URL generation settings:

Property | Value | Default
urls.page | "html" or "clean" | "html"
urls.link | "relative" or "root_relative" | "relative"

urls.page controls public page URLs. "html" preserves generated .html file names. "clean" removes the extension and maps index.html pages to their containing directory.

urls.link controls generated internal links. "relative" writes links from the current page. "root_relative" prefixes links with the selected site's base_path.

CHM target

A CHM target path is a file whose extension is .chm.

Property | Value | Default
title | string | resolved project title

The CHM title controls the window and artifact title. It takes precedence over the title in the selected site definition.

Validation and compatibility

DocInsight rejects invalid JSONC, duplicate properties, null values, a missing or invalid project declaration, unknown properties, invalid field values, unresolved references, and invalid paths or patterns.

An omitted edition always means edition 2026; it will not begin to mean a newer edition when one is introduced. Unsupported editions and required features are rejected before the manifest is interpreted under the current edition.

Unknown fields and enum values are not accepted for forward compatibility. New syntax is introduced through a declared feature or a later edition.

Important defaults

Property | Default
edition | "2026"
requires.features | []
i18n.default_locale | "en-US"
Markdown files | ["**/*.md"]
Asset-set root | manifest directory (.)
Asset-set files | required; no implicit default
Content and asset-set mount | declared entity name
Target string or { "name": ... } content binding | inherit the content mount
target assets | publish no project asset sets
target site | inherit top-level site, otherwise remain unbound
HTML urls.page | "html"
HTML urls.link | "relative"
site.base_path | /
target canonical | false
output.default_targets | all targets in canonical identity order

For a complete configuration, see Manifest examples.


CLI reference | DocInsight Docs

  1. Guide
  2. Reference
  3. CLI command reference

CLI reference

On this page

  1. Commands
  2. Syntax

DocInsight CLI and local server

Commands

  • init command

  • check command

  • build command

  • clean command

  • open command

  • license command

Syntax

console
$ docinsight --help
DocInsight CLI and local server

Usage: docinsight [OPTIONS] <COMMAND>

Commands:
  init     Create a new project manifest
  check    Check documentation projects, content, and sources
  build    Build configured documentation outputs
  clean    Remove generated files owned by the last build
  open     Open generated documentation output
  license  Show and manage license information

Options:
  -h, --help
          Print help

  -V, --version
          Print version

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]


init command | DocInsight Docs

  1. Guide
  2. Reference
  3. CLI command reference

init command

On this page

  1. Syntax

Create a new project manifest

Syntax

console
$ docinsight init --help
Create a new project manifest

Usage: docinsight init [OPTIONS] [PATH]

Options:
  -h, --help
          Print help

Project Options:
      --name <NAME>
          Project identifier (ASCII, e.g. my-library, my_library, or MyLibrary)

      --title <TITLE>
          Project title

      --reference-root <PATH>
          Reference root for authored root-relative paths (relative to the project directory)

  -t, --template <NAME>
          Project template to use

          [default: empty]
          [possible values: empty, markdown, delphi]

      --from-legacy <FILE>
          Import from a legacy .diproj manifest

  [PATH]
          Project directory to initialize

          [default: .]

Init Options:
      --force
          Allow overwriting an existing manifest

      --dry-run
          Report changes without writing files

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]


check command | DocInsight Docs

  1. Guide
  2. Reference
  3. CLI command reference

check command

On this page

  1. Syntax

Check documentation projects, content, and sources

Syntax

console
$ docinsight check --help
Check documentation projects, content, and sources

Usage: docinsight check [OPTIONS]

Options:
  -h, --help
          Print help

Project Options:
      --manifest <PATH>
          Path to a `docinsight.json` or legacy `.diproj` manifest

Target Selection:
  -t, --target <NAME[=PATH]>
          Select a target; append `=PATH` to override its output

      --all-targets
          Select all output targets, ignoring `output.default_targets`

  -f, --format <FMT>
          Select output targets by format

          [possible values: html, chm]

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]


build command | DocInsight Docs

  1. Guide
  2. Reference
  3. CLI command reference

build command

On this page

  1. Syntax

Build configured documentation outputs

Syntax

console
$ docinsight build --help
Build configured documentation outputs

Usage: docinsight build [OPTIONS]

Options:
  -h, --help
          Print help

Project Options:
      --manifest <PATH>
          Path to a `docinsight.json` or legacy `.diproj` manifest

Target Selection:
  -t, --target <NAME[=PATH]>
          Select a target; append `=PATH` to override its output

      --all-targets
          Select all output targets, ignoring `output.default_targets`

  -f, --format <FMT>
          Select output targets by format

          [possible values: html, chm]

Build Options:
  -j, --jobs <N>
          Number of parallel jobs; defaults to the number of available CPUs, up to 16

          [env: DOCINSIGHT_JOBS=]

      --dry-run
          Simulate the building process without producing output files

      --verify-output
          Hash reusable destination files and rewrite any whose content differs

      --open
          Open the built output when finished

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]


clean command | DocInsight Docs

  1. Guide
  2. Reference
  3. CLI command reference

clean command

On this page

  1. Syntax

Remove generated files owned by the last build

Syntax

console
$ docinsight clean --help
Remove generated files owned by the last build

Usage: docinsight clean [OPTIONS]

Options:
      --manifest <PATH>
          Path to a `docinsight.json` manifest

  -h, --help
          Print help

Target Selection:
  -t, --target <NAME[=PATH]>
          Select a target; append `=PATH` to override its output

      --all-targets
          Select all output targets, ignoring `output.default_targets`

  -f, --format <FMT>
          Select output targets by format

          [possible values: html, chm]

      --dry-run
          Report generated files without removing them

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]


open command | DocInsight Docs

  1. Guide
  2. Reference
  3. CLI command reference

open command

On this page

  1. Syntax

Open generated documentation output

Syntax

console
$ docinsight open --help
Open generated documentation output

Usage: docinsight open [OPTIONS] [TARGET]

Options:
  -h, --help
          Print help

Project Options:
      --manifest <PATH>
          Path to a `docinsight.json` or legacy `.diproj` manifest

Target Selection:
  -t, --target <NAME[=PATH]>
          Select a target; append `=PATH` to override its output

  -f, --format <FMT>
          Select a target by format

          [possible values: html, chm]

  [TARGET]
          Target to open

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]


license command | DocInsight Docs

  1. Guide
  2. Reference
  3. CLI command reference

license command

On this page

  1. Syntax
  2. show command
    1. Syntax
  3. set command
    1. Syntax
  4. remove command
    1. Syntax

Show and manage license information

Syntax

console
$ docinsight license --help
Show and manage license information

Usage: docinsight license [OPTIONS] <COMMAND>

Commands:
  show    Show the current license information and its status
  set     Update license information
  remove  Remove the existing license from the system

Options:
  -h, --help
          Print help

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]

show command

Show the current license information and its status

Syntax

console
$ docinsight license show --help
Show the current license information and its status

Usage: docinsight license show [OPTIONS]

Options:
  -h, --help
          Print help

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]

set command

Update license information

Syntax

console
$ docinsight license set --help
Update license information

Usage: docinsight license set [OPTIONS]

Options:
      --email <EMAIL>
          The email of the license

      --key <KEY>
          The key of the license

  -h, --help
          Print help

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]

remove command

Remove the existing license from the system

Syntax

console
$ docinsight license remove --help
Remove the existing license from the system

Usage: docinsight license remove [OPTIONS]

Options:
  -h, --help
          Print help

Output Options:
  -q, --quiet
          Suppress all messages except for warnings and errors

  -v, --verbose...
          Increase output detail (-v for verbose, -vv for full operational details)

Terminal Options:
      --color <WHEN>
          When to use terminal colors

          [possible values: auto, always, never]

      --no-color
          Disable terminal colors

      --progress <WHEN>
          When to display progress indicators

          [possible values: auto, always, never]

      --no-progress
          Disable progress indicators

      --hyperlinks <WHEN>
          When to emit terminal hyperlinks

          [possible values: auto, always, never]

      --no-hyperlinks
          Disable terminal hyperlinks

Interaction Options:
      --no-input
          Never prompt for user input

Logging Options:
      --log-file <PATH>
          Write diagnostic logs to a file

          [env: DOCINSIGHT_LOG_FILE=]

      --log-level <LEVEL>
          Set the minimum diagnostic log level

          [env: DOCINSIGHT_LOG_LEVEL=]
          [possible values: error, warn, info, debug, trace]


Download documentation | DocInsight Docs

  1. Guide

Download documentation

Prebuilt DocInsight documentation packages are available from the online documentation site.

  • Offline HTML — Portable HTML documentation for use in a web browser.

  • CHM — Compiled HTML Help for Windows.

Note

Save the CHM file to a local drive before opening it. If Windows blocks the help content, right-click the .chm file, select Properties, and select Unblock on the General tab if the option is available.

For the latest documentation, visit docs.docinsight.dev.


Get support | DocInsight Docs

  1. Guide

Get support

On this page

  1. Private support
    1. Product support
    2. License and orders
  2. Public channels
  3. Report a problem
  4. Collect diagnostic logs

Start with this documentation for setup instructions, project configuration, authoring guidance, and CLI reference. If you need more help, choose a private or public channel based on the information you need to share.

Private support

Product support

Email support@devjetsoftware.com when your question involves private installation details, activation, licensing, diagnostic logs, or source code. In the Delphi IDE, you can also choose DocInsight > Help > Email Support.

License and orders

Use the secure FastSpring customer portal to manage purchases, invoices, payment details, and renewals. Open the portal from the account link in your order or renewal email. You may be asked to verify the email address used for the purchase.

For purchase and order questions, email sales@devjetsoftware.com.

Public channels

Use the DocInsight issue tracker to report bugs or documentation problems, or to request features that can be discussed publicly.

Use the DocInsight community forum to ask public questions, share workflows, and discuss product usage.

Warning

Do not post license keys, private source code, confidential logs, or customer data in public channels.

Report a problem

When reporting a problem, include:

  • The DocInsight version.

  • The Delphi version, when the problem involves Delphi source or the IDE extension.

  • The command you ran and relevant diagnostic output.

  • A diagnostic log when available.

Use the issue tracker only when this information can be shared publicly. Otherwise, send the report to product support. In the Delphi IDE, you can also choose DocInsight > Help > Report Issue.

Collect diagnostic logs

Create a CLI log file while reproducing the problem:

shell
docinsight check --log-file logs/docinsight.log --log-level debug

For an IDE extension problem, choose DocInsight > Tools > Debug Logging, reproduce the problem, and then choose DocInsight > Tools > Show Logs.

Logs can contain local paths, project details, command-line arguments, source excerpts, or documentation content. Review them and remove proprietary source, customer data, credentials, license keys, and other private information before sharing them.


Guide

Open Guide


Prism

MIT LICENSE

Copyright (c) 2012 Lea Verou

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

------------------------------------------------------------------------------

Atlas Design

MIT License

Copyright (c) Microsoft Corporation.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE

------------------------------------------------------------------------------

Lucide License
ISC License

Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2023 as part of Feather (MIT). All other copyright (c) for Lucide are held by Lucide Contributors 2025.

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

The MIT License (MIT) (for portions derived from Feather)

Copyright (c) 2013-2023 Cole Bemis

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

------------------------------------------------------------------------------

fuzzysort

MIT License

Copyright (c) 2018 Stephen Kamenar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

------------------------------------------------------------------------------

normalize.css

The MIT License (MIT)

Copyright © Nicolas Gallagher and Jonathan Neal

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

------------------------------------------------------------------------------

minireset.css

The MIT License (MIT)

Copyright © 2016 Jeremy Thomas

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


Manage licenses | DocInsight Docs

  1. Guide

Manage licenses

Use docinsight license to view, update, or remove stored license information from a terminal. For first-time activation and trial-mode restrictions, see Activate DocInsight.

Show the current license status:

shell
docinsight license show

Set or replace the stored license:

shell
docinsight license set

Enter the license email and key when prompted. For non-interactive use, pass --email and --key; avoid exposing the key in shared scripts or command logs.

Remove the stored license:

shell
docinsight license remove

docinsight build may prompt for acceptance of the trial license agreement. In automation, use docinsight build --accept-license only when the environment is allowed to accept that agreement.

For all subcommands and options, see the license command reference.