Login

KB

Common pitfalls, recurring AI-agent misconceptions, API misuse and their resolutions. Each entry is an authoritative reference you can link to when the same issue comes up again.

Path tra­ver­sal

Docly's filesystem API accepts only absolute paths from site root — relative path components are not supported, so the path-traversal…

Crea­ting new doc­ly fi­les

New .docly and .json files must be written atomically — build the complete content in a temp folder on a separate drive and copy it into…

Hash fi­les are cac­hed

Hash files render once and are cached, so per-request expressions like #docly.foo(request.Jwt.x)# freeze the first visitor's data and serve…

Use til­de paths in Ja­vaSc­rip­t

Hardcoded leading-slash paths in JavaScript break the moment the app is published under a subfolder. On publish, Docly rewrites href and…

Omit fi­le ex­ten­sion­s in link­s

Docly serves every page at a clean, extensionless URL and resolves the underlying file by name, so internal links must omit the .html and…

Sort fol­der con­tents by a cus­tom fiel­d

Make a folder's contents sortable by adding a CustomColumns entry to the folder's .docly properties: a Formula that reads a field from the…

Ship se­cure user ac­cess fast: let Doc­ly hand­le lo­gin, you hand­le the per­mis­sio­ns

Skip the authentication tax — let Docly's built-in login handle passwords, resets, sessions, 2FA and threat protection for you…

Rea­ding que­ry and form fields in API call­s

Docly API endpoints (#/API/*.js) do not receive an Express-style request object — input arrives via auto-bound function parameters and the…

Build client UI as st­ruc­ture­d web com­ponen­ts

When a client-side Docly solution grows beyond a single page, structure the UI as native Web Components (custom elements) instead of one…

Keep pri­vate da­ta un­der the # fol­der

Anything in a published folder is served directly over HTTP — including raw JSON documents and data files. To keep data out of public…

Group API end­point­s in­to to­pic fol­der­s

Dumping every endpoint as a flat list of .js files directly in #/API/ becomes unreadable and collision-prone as an app grows. Docly maps…

Use mas­ter pa­ges for sha­red layou­t

When several pages or display templates share the same layout — header, footer, navigation, common CSS/JS — define a single master page…

Or­gani­ze pa­ges in­to to­pic fol­der­s

Dropping every .html and .hash file into a single folder produces a long, flat, unbrowsable list and flat, meaningless URLs as a site…

Keep in­dex.­has­h out of con­tent fol­der­s

index.hash is a fallback-resolved file: a single #/Folder/index.hash renders the listing for every folder, and #/Root/index.hash is served…

Se­para­te co­de from con­tent for non-de­velo­per user­s

When non-developer users will administer data in a Docly solution, move display assets (index.hash, shared CSS/JS, masters, partials) into…

Cac­he-bus­ting bund­les with as­setUr­l

Browsers cache static files, so an unchanged bundle URL can serve stale JS/CSS for up to a day after a publish. Wrap your own <script src>…

Op­timi­ze pa­ge per­for­man­c­e

When a Docly page scores poorly on PageSpeed Insights, use Claude Code and the Claude Chrome plugin to diagnose which bottleneck actually…

Work sa­fely on a li­ve si­te

On Docly the folder on disk is production - no git, no staging, no build step - so pointing an AI agent straight at a live site is…

Use a sc­ratch hash fi­le to test Doc­ly func­tion­s

A new .hash file is live the moment you save it and can print anything the server computes, so a throwaway scratch page is the cheapest way…

The si­te dri­ve is Web­DAV not a dis­k

A Docly site mapped to a drive letter is not a disk - net use reports Web Client Network, meaning WebDAV over HTTPS. Every cd and stat is…

Sto­re re­pea­ting rows in a tab­le fiel­d

Store a repeating list of rows in a schema by adding a Table field: it defines an Array key and Columns, and each record holds an array of…

Test layouts in real view­port­s

Resizing the browser window or using devtools device emulation checks one width at a time, and scrollable frames hide overflow that…

Sca­le and con­vert ima­ges in Doc­ly

Docly scales and converts images on serving, but the URL is not /image.jpg/WxHxM/name.webp — it is /image.jpg/<embeddedId>/WxHxM/name.webp.…

Gi­ve lin­ked ima­ges SEO-friend­ly fi­lena­mes

When you link an embedded image through Docly's scaling URL, the last path segment — the "virtual name" — becomes the image's public…

Rest­rict and re­gis­ter ima­ge si­zes

The scaled image URL (/foto.jpg/1200x800x0/navn.jpg) is open by default: every unique size is a cache miss with heavy scaling and a new…

Use AVIF and WebP ima­ge for­mat­s

You keep uploading JPEG/PNG as before; Docly converts on serving, and the file extension on the display name in the image URL decides the…

Do not build fi­le and ima­ge URLs by han­d

linkImage and linkFile now cover every linking case, including a file stored on another document, so there is no longer a reason to…

Doc­ly Ja­vaSc­rip­t is not No­de

Docly's server-side JavaScript is HashJS running on V8 — not Node. There is no npm, no package.json, no node_modules, no require(), no…

The map­ped dri­ve is not a git wor­king co­py

A Docly workspace mapped as a drive is not a git working copy, and running git init inside it creates a .git directory in the live…

Re­naming a sc­hema field does not mig­rate do­cument­s

Renaming a field in the schema designer updates the editor and the generated form, not the documents already saved - those keep the old…

Fal­se wri­te-ve­rifi­cat­ion fai­lures on the Web­DAV dri­ve

A tool writing to the WebDAV-mapped Docly drive reports "Write verification failed: <file> is N bytes on disk, expected M". The two numbers…

Do not crea­te a # fol­der in­side a pub­lish temp­late

A publish template folder is itself the # namespace for the sites that use it, so a path the documentation writes as #/site.json means…

Agent skills do not load from the map­ped dri­ve

Claude Code does not discover project skills in a workspace's .claude/skills/ folder when the workspace is opened over the WebDAV-mapped…

Set up AI agent inst­ruc­ti­on fi­les for a works­pac­e

An agent instruction file's job is to point, not to teach: make reading the knowledge base mandatory before and after every task, then map…

Un­resol­ve­d na­mes in hash exp­res­sio­ns ren­der emp­ty

A #name# expression in a hash file that resolves to nothing renders as an empty string. Nothing is thrown and nothing is logged — unlike…