> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# Heretto integration

> Load DITA content directly from your Heretto CCMS for testing.

Heretto is a component content management system (CCMS) for technical documentation. Doc Detective can load Darwin Information Typing Architecture (DITA) content directly from your Heretto CCMS. You can then run tests against live content without manual exports or local copies.

> **Note**
>
> This integration requires an appropriate Heretto license with API access.

## Prerequisites

Before using the Heretto integration, you need:

* A Heretto account with API access
* Your Heretto organization ID
* Heretto username and API token
* A publishing scenario configured in Heretto with `transtype` set to `dita`

## Configuration

Add entries to the `integrations.heretto` array in your config file:

```json
{
  "integrations": {
    "heretto": [
      {
        "name": "my-docs",
        "organizationId": "your-org-id",
        "username": "your-username",
        "apiToken": "your-api-token"
      }
    ]
  }
}
```

### Configuration options

| Option           | Type    | Required | Description                                                                                                              |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `name`           | string  | Yes      | Identifier for this integration. Use this name in the `heretto:<name>` input syntax.                                     |
| `organizationId` | string  | Yes      | Your Heretto organization ID. You can set this via the `HERETTO_ORG_ID` environment variable.                            |
| `username`       | string  | Yes      | Your Heretto username. You can set this via the `HERETTO_USERNAME` environment variable.                                 |
| `apiToken`       | string  | Yes      | Your Heretto API token. You can set this via the `HERETTO_TOKEN` environment variable.                                   |
| `scenarioName`   | string  | No       | Publishing scenario name in Heretto. Defaults to `Doc Detective`.                                                        |
| `uploadOnChange` | boolean | No       | If `true`, Doc Detective monitors screenshots during test runs and automatically uploads changed images back to Heretto. |

## Using Heretto as an input source

Reference your Heretto content using the `heretto:<name>` syntax in your input paths:

```json
{
  "input": ["heretto:my-docs", "./local-docs"],
  "integrations": {
    "heretto": [
      {
        "name": "my-docs",
        "organizationId": "your-org-id",
        "username": "your-username",
        "apiToken": "your-api-token"
      }
    ]
  }
}
```

When Doc Detective encounters `heretto:my-docs`, it:

1. Finds the publishing scenario named `Doc Detective` (or your custom `scenarioName`)
2. Triggers a publishing job in Heretto
3. Polls the job until the required output is available
4. Downloads and extracts the published DITA content
5. Processes the DITA files for test detection

> **Note**
>
> Doc Detective checks for the required DITA content files in the job output instead of relying on the job status code. Content loads successfully as long as the expected `.ditamap` files are generated, even if Heretto reports the job as incomplete.

## Environment variables

For security, store credentials as environment variables rather than in config files:

| Environment variable | Description                  |
| -------------------- | ---------------------------- |
| `HERETTO_ORG_ID`     | Your Heretto organization ID |
| `HERETTO_USERNAME`   | Your Heretto username        |
| `HERETTO_TOKEN`      | Your Heretto API token       |

Example using environment variables with `loadVariables`:

```json
{
  "loadVariables": ".env",
  "input": "heretto:my-docs",
  "integrations": {
    "heretto": [
      {
        "name": "my-docs",
        "organizationId": "$HERETTO_ORG_ID",
        "username": "$HERETTO_USERNAME",
        "apiToken": "$HERETTO_TOKEN"
      }
    ]
  }
}
```

## Publishing scenario requirements

Your Heretto publishing scenario must have:

* The `transtype` parameter set to `dita`
* A file picker parameter configured to select the root DITA map

Doc Detective looks for a scenario named `Doc Detective` by default. Use the `scenarioName` option to specify a different scenario.

## Example workflow

1. Create a `.env` file with your Heretto credentials:

   ```
   HERETTO_ORG_ID=your-org-id
   HERETTO_USERNAME=your-username
   HERETTO_TOKEN=your-api-token
   ```

2. Add Heretto to your `config.json`:

   ```json
   {
     "loadVariables": ".env",
     "input": "heretto:product-docs",
     "integrations": {
       "heretto": [
         {
           "name": "product-docs",
           "organizationId": "$HERETTO_ORG_ID",
           "username": "$HERETTO_USERNAME",
           "apiToken": "$HERETTO_TOKEN",
           "scenarioName": "Doc Detective"
         }
       ]
     }
   }
   ```

3. Run Doc Detective to load and test your Heretto content:

   ```bash
   npx doc-detective runTests
   ```

Doc Detective fetches your DITA content from Heretto and processes it using the standard DITA file type patterns. Any inline or detected tests in your DITA files run automatically.

## Next steps

* Learn about [DITA input format](/docs/test-docs/input-formats/dita) for DITA-specific markup patterns
* Learn about [inline tests](/docs/test-docs/inline) for defining tests in your documentation
* Learn about [detected tests](/docs/test-docs/detected) for automatic test generation