Start new sites in strict JavaScript mode

1. 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.

2. 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; alone on a line	XOR assignment (since October 2026; before that the line did nothing)	XOR assignment
   a ^= b where the value is used (if, #a ^= b#, x = (a ^= b))	A string comparison	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.

3. 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 is built on an app, the site only needs the hashjs block. A site inherits the app's settings key by key, so a #/site.json containing only hashjs keeps the template's headers, image policy and security level. A hashjs block in the app's site.json applies to every site built on it, so put it there only when all of them are ready. The compile check in the editor 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:

   #{ write("abc".Length === 3 ? "compatibility mode" : "strict mode"); }#

   .Length with a capital L only exists in compatibility mode. If the page prints compatibility mode, 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.

Last reviewed 07 Oct 2026