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.

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

{
  "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}}.

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.

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

{
  "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.

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

{
  "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.