Site.json config file Last updated: 20. Oct 2026

The headers property in site.json is the recommended place to set HTTP security headers for a single site. For headers that every site on an app should share, put them in the app — in headers.json in the template's root, or in the template's site.json — see the note at the top of this page. The following headers protect against common web vulnerabilities such as Cross-Site Scripting (XSS), Clickjacking, MIME type sniffing and insecure transport, and they are equipped with sensible Docly defaults.

A full, recommended site.json example using these headers is shown at the end of this chapter.

The optional images block controls image-size policy (which scaling sizes are allowed on image URLs), the default output format for scaled images and the encoder quality used when they are encoded. It is shared per folder — several templates and aliases share the same site.json, so the policy is managed in one place.

The settings from the Image sizes tab and the sizes Docly discovers are written to the site's #/images.json — never to site.json, and never to the app. An images section in site.json still works, but Docly moves it to #/images.json the first time it saves image settings. A site's allowedSizes replaces the app's list as a whole.

For full details on the size policy and the admin 'Image sizes' tab, see Image scaling & allowed sizes. For a step-by-step walkthrough of turning the policy on and registering the sizes, see the KB article Restrict and register image sizes. For output formats, see Image output formats (WebP / AVIF).

The WxHxM key: W = width in px (0 = free), H = height in px (0 = free), M = scaling mode (0 = ScaleToFit default, 1 = ScaleToFill, …). The key is the URL segment: /photo.jpg/1200x800x0/name.jpg. "1200x800" is treated as mode 0.

The optional security block sets how strictly the site checks its visitors. From elevated and up, the visitors the level covers must pass a Cloudflare Turnstile check before the site serves anything — including pages that are already in the site cache. A visitor who passes gets a clearance that lasts clearanceMinutes, and browses normally until it runs out.

Raise the level while a site is being hammered by bots or scrapers, and lower it again when the attack is over — or set until so the site goes back to the platform default by itself (see Platform default below).

Known attack URLs. From elevated and up, a request for a URL that scanners probe for — wp-login.php, .env, /.git/config, /wp-admin, /admin and similar — that your site does not have gets the check instead of the 404 page, even on the first request from an address. Every such request is counted against the visitor's IP, and an address that keeps probing is eventually blocked by the firewall. A visitor who passes the check gets the site's normal 404.

If your site really has such a page — an old .php page, or a page at /admin — nothing changes for it: it is served like any other page, and visiting it never counts against anyone. You do not need to add it to exclude.

What a visitor without clearance gets:

• Page views (a normal page load in the browser) get a challenge page with the Turnstile check, HTTP 403. When the check passes, the page reloads with the content.
• Everything else — fetch and API calls, images, files, form posts — gets HTTP 403 with {"ResultCode": -213, "Message": "Verification required."}.
• Both responses are sent with Cache-Control: no-store, so neither the browser nor a CDN in front of the site keeps them.

The clearance is a signed cookie, docly_clr_<site id>: HttpOnly, Secure on HTTPS, SameSite=Lax, and valid for this site only. It is not tied to the visitor's IP address, so people on mobile networks keep it when their address changes. Clearances are reset when the server restarts; visitors then pass the check again.

Reserved path: while the level is above normal, <site>/__docly/clearance is used by the challenge page and is not served from the site.

The country is taken from Docly's cache of earlier lookups — the check never waits for a new lookup. A visitor whose country is not known yet counts as neutral: checked on high, not on elevated. Which countries have high and low trust is set centrally by Docly.

Earlier form: "underAttack": true still works, and means the same as "level": "underAttack". It only applies when level is not set.

Keys in site.json are not case-sensitive; the documented form is camelCase.

The optional hashjs block decides how the site's .hash pages are compiled. By default they run in compatibility mode: plain JavaScript plus Docly's older template syntax — bracket conditions such as #[Field]#…#[/Field]#, the text operators ^=, ^!, ~=, ~! and $=, function names in any letter case, and .Length / .Count.

Set compatibilityMode to false and the pages are compiled as plain JavaScript, the same way files under #/API/ always are.

Recommended for new sites: start with compatibilityMode set to false — the strictest mode. See Start new sites in strict JavaScript mode.

A site on an app only needs the block. A site inherits the app's settings key by key, so a #/site.json with only hashjs in it keeps the template's headers, image policy and security level (see the note at the top of this page).

What it covers. The site's own .hash pages, including display templates such as #/Blog post.hash, and the files they include. It does not cover templates stored in a schema — those have their own Modern syntax setting on each template, because they are also rendered outside the site (downloads, previews, PDF). See Create display templates for your schemas.

Before you switch it off on a live site, make sure no page uses the bracket syntax or the text operators: a page that does stops compiling and returns an error. The compile check in the editor reads the same setting, so open and save the pages after changing the value to see which ones fail. It reads the site.json in the workspace itself — a value that only comes from an app is not seen by the check.

Related: Template operators differ from JavaScript in compatibility mode.

The login block (or the file #/login.json) holds the name and logo on the Docly sign-in page.

"login": {
  "name": "Acme Customer Portal",
  "logo": "/assets/acme-icon.png"
}

The router block (or the file #/router.json) names a script in #/Services/ that runs before every request to the site. It lets the request through, serves another path, redirects it or answers it itself — and can set cookies and headers on the way.

"router": { "script": "Router.js" }

A path inside #/Services/ — Router.js, or with folders, Routing/Router.js — using letters, digits, ., _, - and /, ending in .js; no part may start with .. An invalid path, a missing file or a router section that cannot be read answers every request with 500. On a publication that requires sign-in, Docly's sign-in comes first and the router runs after it. See The site router.