Login

Editing Docly documents programmatically Last updated: 08. May 2026

How to safely create and edit Docly documents from outside the Docly UI — using a mapped WebDAV drive, scripts, AI coding agents, or any other external tool.

Why this matters

Docly workspaces can be mapped as a WebDAV drive (see Using Claude Code Directly on a Mapped Docly Drive). Once mapped, you can edit files with any tool — VS Code, scripts, IDE plugins, or AI coding agents like Claude Code or Cursor.

Most files behave like ordinary files. But .docly documents are different — they are JSON files bound to a Docly schema at creation time. The drive enforces that binding, and getting it wrong leaves you with an unregistered file that won't open as a document.

Editing an existing .docly file

Editing an existing document is straightforward — open the file, change the JSON, save. The schema binding is already in place and survives in-place writes.

Every save must be valid JSON. The drive rejects writes to .docly and .json files when the result is not parseable, so there is no way to leave a file temporarily invalid between edits. If a refactor would break the JSON mid-way (e.g. removing one element and adding another in separate steps), do the whole change in a single edit — or build the new content in a temp folder and overwrite the file with a copy.

Creating a new .docly file

This is the part that trips people up. Writing a new .docly file directly into the drive does not work — the drive registers the file as a generic upload (no schema binding), and it stays that way even after you delete and rewrite. The filename is then burned for that path: re-using it requires clearing the cached binding through the Docly UI.

Use this pattern instead:

  1. Build the complete file in a temp folder outside the Docly drive — somewhere on your local disk. Get the JSON fully correct first, with no partial writes.

  2. Copy the file into the Docly drive in one operation. The drive sees a complete file appear at a .docly path, parses it, looks up the schema, and registers the binding atomically.

  3. Verify the size on the destination. The drive normalizes the file and adds metadata, so the destination file is slightly larger than the source. A destination file that is only 2 bytes means the registration failed.

  4. Delete the temp source.

Concrete example in PowerShell:

# 1. Build the complete file in temp
$temp = "$env:TEMP\My new doc.docly"
Set-Content -LiteralPath $temp -Value $jsonContent -Encoding UTF8

# 2. Copy (NOT move) into the drive
Copy-Item -LiteralPath $temp `
          -Destination "L:\Websites (Example)\my-site\My new doc.docly"

# 3. Verify size on destination > source
# 4. Clean up
Remove-Item -LiteralPath $temp

Why not Move-Item?

Move-Item (or mv on Unix-like systems) seems like the natural choice, but it fails. When the move begins, the drive sees the destination path and pre-creates a 2-byte placeholder. The actual file move then fails with The file exists.

Use Copy-Item, then optionally remove the source as a separate step.

How to tell if registration succeeded

  • File size: the destination is larger than the source by a few hundred bytes — that is metadata the drive added. A 2-byte file means failure.

  • Directory listing: correctly registered files show with the .docly suffix. Files shown without the suffix have not been registered as documents.

  • Open the document: in Docly it should open with the right schema-driven editor or render correctly on the web. If it opens as raw text or an upload, registration failed.

Recovering from a misregistration

If a .docly file gets registered as a generic upload, the simplest fix is to use a different filename. Deleting and rewriting to the same name does not clear the cached binding from the drive.

If you must keep the original filename, clear the cached binding via the Docly UI before retrying — open the workspace in Docly, locate the misregistered file, and remove it from there rather than from the mapped drive.

Notes for AI coding agents

If you are configuring an AI coding agent (Claude Code, Cursor, etc.) to work in a Docly workspace, drop a CLAUDE.md (or equivalent) in the workspace root with the temp+copy rule above, plus a strong note that the filename is burned on a failed first write. Without that guidance, agents typically default to direct writes and end up with misregistered files on their first attempt.

Rule of thumb: treat each new .docly filename as a one-shot. Get the temp+copy right the first time.