Start new sites in strict JavaScript mode

Best practice Recommended

Start every new site in the strictest mode: "hashjs": { "compatibilityMode": false } in the workspace's own #/site.json, and Modern syntax ticked on every schema template you create. Then .hash pages and templates are plain JavaScript, exactly like files under #/API/ — no bracket conditions, no text operators that look like JavaScript but compare strings, no case-insensitive function names. A new site has no old syntax to keep alive, so the setting costs nothing on day one and is expensive to introduce later, when pages already depend on the old syntax. Compatibility mode remains the default only so existing sites keep working.

Applies to: New sitesHASH filesSchema templatessite.json

What you'll see

You are creating a new site, a new workspace or a new schema template — or you are about to write the first .hash page in one.

What's actually happening

Docly compiles .hash pages and schema templates in one of two modes:

	Compatibility mode (default)	Strict mode
Language	JavaScript plus Docly's older template syntax	Plain JavaScript — the same as `#/API/`
`a ^= b;`	A string comparison; the line does nothing	XOR assignment
`#[Field]#…#[/Field]#`	Bracket condition	Syntax error
`Trim(x)`, `Mul(a, b)`, `list.Count`	Work	`docly.trim(x)`, exact names, `.length`
`let $x`	Syntax error	Allowed

Compatibility mode exists so that sites written years ago keep rendering. It is the default for that reason only. On a new site it gives you nothing, and it costs you: code you test in an API file can behave differently in a page, and some mistakes are silent instead of compile errors. See Template operators differ from JavaScript in compatibility mode.

The switch is cheap on day one and expensive later. Once pages use the old syntax, every one of them has to be converted before the mode can change — and a page that is missed stops compiling.

There are two levels, because site pages and schema templates are rendered by different paths:

Site pages — the site's .hash files, including display templates like #/Blog post.hash: the hashjs block in site.json.
Schema templates — templates stored inside a schema, also used for downloads, previews and PDF: the Modern syntax setting on each template.

Files under #/API/ are always strict; they need no setting.

What to do

1. Put the setting in the workspace's own #/site.json when you create the site:

{
  "hashjs": {
    "compatibilityMode": false
  }
}

If the site gets its site.json from an app, the site needs a complete file of its own. A site that overrides anything at all — hashjs included — must have its own #/site.json with the full content: copy the template's whole file and add the hashjs block to the copy. A site's own file replaces the template's as a whole; nothing is merged key by key. A file containing only hashjs silently drops the template's headers, image policy and security level for that site. The compile check in the editor also reads the workspace's own file only.

See Site.json config file.

2. Tick Modern syntax on every schema template you create — in the template's settings in the schema editor.

3. Check that it took effect. Drop this into a scratch page and open it:

#{ let a = 5; a ^= 1; write(a); }#

Strict mode prints 4. Compatibility mode prints 5 — then the setting is not being read; check that it is in the workspace's own #/site.json and spelled hashjs / compatibilityMode.

Existing sites: keep the default until the pages are converted. Remove bracket conditions and the text operators (^=, ~=, ^!, ~!, $= …), then switch, then open and save each page to confirm it compiles. Do one site at a time, and do it on a copy first if the site is busy — see Work safely on a live site.

What you'll see

What's actually happening

What to do

Related