DocsUpdated 25 Oct 2026

Publishing a site

Publishing gives a folder or a single document a web address on one of your subscription's domains. This page covers the publish dialog, addresses, your own domain, apps, sign-in, the page cache, and publishing from API scripts and the docly CLI.

Before you publish

A subscription with a verified domain. The workspace must have a subscription, and the subscription at least one verified domain. Without them the publish dialog says so, and publishing is refused. See Your own domain below.
The Publish right on the folder or document. The owner has it; in a custom share it is a right of its own.
Private data under #. Everything in a published folder is reachable by its path. Put data, configuration and secrets under # — see Keep private data under the # folder and Sign-in and access.

Publish a folder or a document

Open the publish dialog with Publishing ... in a folder's properties, or Publish online ... in the document editor. The dialog lists the publications the item already has; New adds one, and the menu on a row edits or removes it.

Field	What it does
Address	The domain and the path under it. At the domain root publishes on `https://example.com/`. An empty path becomes the item's name, with spaces turned into `-`.
App (folders)	Use an app runs the folder with an app — see Apps below. Off: the folder is published as it is, with its own files and its own code.
Format (documents)	What the address delivers — a web page or a file. The choices are the templates of the document's schema, and one is required.
Require login	Off: open to everyone. On: only signed-in Docly users with access. See Public or sign-in below.
Customizable sign-in page (folders)	A name and logo on the Docly sign-in page, when the subscription includes it. See Sign-in and access.

A folder's address ends with / (https://example.com/docs/) and serves everything below the folder. A document gets one address of its own (https://example.com/price-list). A document inside a published folder is also reachable through the folder's address — docly published shows such rows as "via folder".

Addresses and aliases

The path under the domain is the publication's alias.

One address, one publication. An address that is already published — by anyone — is refused, and the message names the address that is taken.
One item, several publications. The same folder can be published on another domain, on another path or with another app. Each is a publication of its own, and they share the folder's #/site.json and settings files.
The longest match wins. https://example.com/admin/ can be its own publication while another one sits on the root of example.com. Requests below /admin/ go to the first.
Rules: an alias may contain / (customers/ola). A numeric alias is refused, and aliases that start with app/ or api/ are reserved.
Changing the address is done by editing the publication. The old address stops answering at once.

Your own domain

A domain belongs to one subscription, and only workspaces on that subscription can publish on it. Add it in Docly Cloud:

Open Subscription, choose the subscription and click Add domain.
Copy the CNAME-record value the page shows. It has the form S….dns.docly.net and is the same for every domain on the subscription.
At your DNS provider, create a CNAME record for the name you want — for example www.example.com — that points to that value.
Enter the domain name on the page and click Submit request. The domain is listed as Pending approval ....
Docly checks that the name resolves to Docly and approves the domain, and you get an e-mail when it is active. Once your DNS is in place you can click Check now on the domain to ask for a check.
The domain now appears in the publish dialog of every workspace on the subscription.

The root of a domain (example.com): many DNS providers do not allow a CNAME there. Use the provider's ALIAS/ANAME record if it has one, or publish on www and let the provider forward the bare domain.
www.example.com and example.com are two domains. To answer on both, publish on one and use your DNS provider's URL forwarding for the other — or add both and give each its own publication.
A domain that is in use cannot be deleted. Remove the publications on it first.
From scripts, docly.getDomains() lists the verified domains on the workspace's subscription — see getDomains.

Apps

An app is a folder whose folder type is Docly App. It holds what runs a site — templates, API/ scripts, Root/ and Folder/ files, site.json — while the published folder supplies the content. One app can run many sites, and one folder can be published with several apps: for example one for administration and one for the public pages.

The app's root is #. When a site runs an app, a path such as #/site.json or #/API/orders.js is looked up in the site's own # folder first, then in the app's root (site.json, API/orders.js). The site's own file always wins. Never create a # folder inside an app — see Do not create a # folder inside an app and The Root folder.

Make a folder an app: set its folder type to Docly App in the folder's properties. The fields are Title, Description, Image and Require login. An app with Require login cannot be published without sign-in.
Use it: turn on Use an app in the publish dialog and pick the app, or Other folder … for one that is not in the list. From the CLI or a script, pass the app folder's guid as the template.
Settings are inherited from the app key by key; the site only sets what differs. See Configure site settings and inherit them from the app and Site.json config file.
A site never writes into the app. docly.saveFile or patchFile on a file that only exists in the app gives the site its own copy. Functions that delete, rename, move, tag or share such a file are refused (error 110).
A change in the app reaches every site that runs it — their page caches are rebuilt, see below.

Public or sign-in

Require login sets the publication's authMode. The same values are used by the CLI (--auth) and by scripts (authMode):

authMode	Meaning
empty	Public. Anyone can open every address the publication serves.
`2`	Sign-in with a Docly account: the browser is sent to the Docly sign-in page and back. This is what Require login sets.
`3`	Accepted, and signs in the same way as `2`.

Any other value is refused (error 8). With sign-in, a visitor needs a share with Visit access to what they open. Who sees what, the sign-in page and your own sign-in with the site router are covered in Sign-in and access.

The page cache

Docly caches what a publication serves, and the cache is always on — there is no setting to turn it off, neither in the publish dialog nor in site.json. A page is rendered once per address, and the same output goes to every visitor after that — also on a publication with sign-in, where all signed-in users share it. The query string is not part of the address the cache uses. API calls, POST requests, rewrites from the site router and answers with another status than 200 are not cached.

It is rebuilt by itself. A cached copy is only used while it is newer than the last change to the published folder (any file or folder below it), to its app and to the publication itself. A browser that asks with If-Modified-Since gets 304 Not Modified until then. Saving the publication — for example switching it to another app — counts as a change, so the site is rendered with the new app on the next request.
Clear it by hand in the site console: the Cache tab has Clear for one site and Clear All Cache for all of them.
Never put per-visitor data in a page — the first visitor's output is served to everyone. Fetch it from an API script in the browser. See Hash files are cached.
Content that must be fresh on every request belongs in an API script (/API/…), which is never cached. Minification of what is cached is set in the minify section of site.json.

Publishing from API scripts

An API script can publish folders and documents inside its own site — typically a customer site it has just created under #/Websites/ — with publishFolder and publishDocument, and remove them again with unpublish. The functions require SaaS on the workspace's subscription, publish as the user who published the site, and go through the same checks as the publish dialog. getPublications lists where the workspace is published.

// #/API/create-site.js — a new customer gets a website
export default (slug, html) => {
    if (request.method != "POST") throw new Error("Verb not supported");

    const path = "#/Websites/" + slug;
    docly.createFolder(path);
    docly.saveFile(path + "/index.html", html);

    const domain = docly.getDomains()[0].domain;
    const pub = docly.publishFolder(path, { domain: domain, alias: slug });
    return { url: pub.url, guid: pub.guid };
};

An existing publication cannot be changed from a script: call unpublish and publish again. Details and error texts: Publish folders and documents from API scripts.

Publishing with the docly CLI

The CLI reads and changes publications the same way the dialog does. publish and unpublish change something, so the folder must be opened for writing with docly unlock first. A reference is a folder guid or a path from the instance root.

docly sites --mine                              # every site you can see, and the folder it comes from
docly published "/Example/Docs"                 # publications on a folder (--doc for a document)

docly unlock "/Example/Docs"
docly publish "/Example/Docs" --alias docs --domain example.com
docly publish "/Example/Docs" --alias docs --domain example.com --template <app guid> --auth 2 --id <publication guid>
docly unpublish <publication guid> "/Example/Docs"

--id updates a publication, and replaces every field. Pass --alias, --template and --auth again: an option you leave out falls back to the folder name, no app and a public site.
--domain takes the domain name or its id; with only one domain it can be left out. --template is the app folder's guid.
Publishing a document needs --template — the schema's template. With one template it is picked for you; with several, the CLI lists them.
docly published prints each publication's guid, address, type, authMode and app, and the docly unpublish line to remove it. Rows marked "via folder" come from a published folder above; unpublish that folder instead.
See How an AI agent should use the docly CLI and Work safely on a live site.