Configuration Reference

Complete reference for the docsync.config.json configuration file.

File Location

The CLI looks for configuration in this order:

Path specified via --config flag
docsync.config.json in current directory
poliage.config.json in current directory
.poliage/config.json in current directory

Schema

{
  "$schema": "https://poliage.com/schemas/config.json",
  "project": "string",
  "version": "string",
  "defaults": { /* DefaultOptions */ },
  "captures": [ /* CaptureConfig[] */ ],
  "output": { /* OutputConfig */ }
}

Root Fields

`project`

Required • string

The project slug matching your Poliage dashboard project.

{
  "project": "my-documentation"
}

`version`

Required • string

Configuration schema version. Currently "1.0.0".

`defaults`

object

Default options applied to all captures unless overridden.

{
  "defaults": {
    "viewport": { "width": 1280, "height": 720 },
    "deviceScaleFactor": 2,
    "format": "png"
  }
}

`captures`

Required • CaptureConfig[]

Array of capture configurations.

`output`

object

Output configuration.

{
  "output": {
    "directory": ".poliage/captures",
    "clean": true
  }
}

CaptureConfig

`name`

Required • string

Unique identifier for the capture. Used as the filename.

`url`

Required • string

URL to capture. Can include environment variables.

{
  "url": "https://app.example.com",
  "url": "${BASE_URL}/dashboard"
}

`selector`

string

CSS selector for element capture. If omitted, captures full page.

{
  "selector": ".main-content",
  "selector": "#login-form",
  "selector": "[data-testid='hero-section']"
}

`viewport`

object

Browser viewport dimensions.

{
  "viewport": {
    "width": 1280,
    "height": 720
  }
}

`deviceScaleFactor`

number • default: 1

Device pixel ratio. Use 2 for retina screenshots.

`fullPage`

boolean • default: false

Capture the full scrollable page instead of just the viewport.

`padding`

number | object

Padding around selected element.

{
  "padding": 16,
  "padding": { "top": 20, "right": 16, "bottom": 20, "left": 16 }
}

`wait`

object

Wait condition before capture.

{
  "wait": {
    "type": "selector",
    "value": ".content-loaded",
    "timeout": 5000
  }
}

Wait types:

Type	Value	Description
`selector`	CSS selector	Wait for element to exist
`visible`	CSS selector	Wait for element to be visible
`hidden`	CSS selector	Wait for element to disappear
`networkidle`	—	Wait for network to be idle
`timeout`	milliseconds	Wait for fixed time
`function`	JS code	Wait for function to return true

`auth`

object

Authentication configuration.

{
  "auth": {
    "type": "cookie",
    "cookies": [
      {
        "name": "session",
        "value": "${SESSION_COOKIE}",
        "domain": "app.example.com"
      }
    ]
  }
}

Auth types:

Type	Description
`cookie`	Set cookies before navigation
`basic`	HTTP Basic authentication
`bearer`	Bearer token in Authorization header

`format`

"png" | "jpeg" | "webp" • default: "png"

Output image format.

`quality`

number • default: 80

JPEG/WebP quality (1-100).

`clip`

object

Capture a specific region.

{
  "clip": {
    "x": 0,
    "y": 0,
    "width": 800,
    "height": 600
  }
}

`actions`

Action[]

Actions to perform before capture.

{
  "actions": [
    { "type": "click", "selector": ".menu-button" },
    { "type": "wait", "timeout": 500 },
    { "type": "type", "selector": "input", "text": "Hello" }
  ]
}

Action types:

Type	Properties	Description
`click`	`selector`	Click an element
`type`	`selector`, `text`	Type into an input
`scroll`	`x`, `y`	Scroll to position
`wait`	`timeout`	Wait milliseconds
`hover`	`selector`	Hover over element
`select`	`selector`, `value`	Select dropdown option

Complete Example

{
  "$schema": "https://poliage.com/schemas/config.json",
  "project": "my-saas-docs",
  "version": "1.0.0",
  "defaults": {
    "viewport": { "width": 1280, "height": 720 },
    "deviceScaleFactor": 2,
    "format": "png"
  },
  "captures": [
    {
      "name": "homepage",
      "url": "https://app.example.com"
    },
    {
      "name": "dashboard",
      "url": "https://app.example.com/dashboard",
      "auth": {
        "type": "cookie",
        "cookies": [{ "name": "session", "value": "${TOKEN}", "domain": "app.example.com" }]
      },
      "wait": { "type": "selector", "value": ".dashboard-loaded" }
    },
    {
      "name": "settings-modal",
      "url": "https://app.example.com/settings",
      "selector": ".settings-modal",
      "actions": [
        { "type": "click", "selector": ".open-settings-btn" },
        { "type": "wait", "timeout": 300 }
      ]
    }
  ],
  "output": {
    "directory": "./docs/screenshots",
    "clean": false
  }
}