Security Headers in the headers.json file Last updated: 19. Jun 2026

The headers.json file is the legacy configuration format for HTTP headers in Docly. New sites should use the headers property in site.json instead. The headers.json file is still read by Docly for backwards compatibility, but no new features are added to it.

Use site.json instead

headers.json is legacy. New sites should configure HTTP headers — including security headers like Content-Security-Policy and Strict-Transport-Security — via the headers property in site.json.

site.json is the current canonical place for per-site configuration and supports the same header keys and values as the legacy headers.json.

If you have an existing headers.json file in your workspace, it continues to work. You can migrate by moving the contents into the "headers" block of site.json and deleting the headers.json file.

Migration example

Move the key/value pairs from #/headers.json into the headers block of #/site.json:

// Old: #/headers.json
{
    "Content-Security-Policy": "default-src 'self';",
    "X-Frame-Options": "SAMEORIGIN"
}

// New: #/site.json
{
    "headers": {
        "Content-Security-Policy": "default-src 'self';",
        "X-Frame-Options": "SAMEORIGIN"
    }
}

For the full list of recommended security headers and their values, see the Security headers chapter in site.json config file.