# Site settings

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.