Last Updated: 8/19/2026

Jolli Sites

Overview

A Site is a published documentation website built from a Space. One Space can power more than one Site (a public one and an internal-only one drawing from the same Articles, for example). You don’t write content on a Site. Writing happens in a Space; a Site is the published output.

Prerequisites

• An existing Space with content to publish.
• The sites.edit permission, which the Owner and Admin roles carry. The built-in Member role does not, so a Member cannot create or publish a Site - ask an Owner or Admin.
• For a custom domain, access to your registrar’s DNS records.

Create a Site

From the sidebar, click + next to Sites. The wizard has four steps (three for Spaces backed by a git repo, which take their branding from the repo).

Basics

• Display Name - the human-readable title shown in the browser tab and the Site header. Example: Orbit SDK Docs.
• Site Name - Lowercase letters, digits, and hyphens; minimum 3 characters. Becomes part of the URL.
• Subdomain - optional; must start and end with a letter or digit, no consecutive hyphens (3–63 characters). Blank means Jolli generates one from the Site Name.

A live URL preview (docs-account.jolli.site) updates as you type. You can point your own domain at the Site afterward.

Content

Pick the Space the Site pulls Articles from. What happens next depends on how that Space is backed.

A regular Space. You choose which Articles go on the Site, not just which Space. Include all articles is the simple path: leave it on and every published Article is included, now and as you add more. Turn it off and you get a checkbox tree of the Space’s folders and Articles, with Select all, Deselect all, and a search box; ticking a folder ticks everything under it. Next stays disabled until either include-all is on or you have picked at least one Article. However you select them, the Space’s folder structure becomes the structure of the Site.

A Space backed by a git repository. There is nothing to select - every Article comes across - so instead Jolli reads the repository’s site.json and tells you what it found:

• site.json looks good - it summarizes the title, theme pack, header items, and whether a footer is defined, then lets you continue.
• Using folder structure for navigation - no site.json in the repository. Jolli generates the sidebar from your folders and you can continue; add the file later to take control of it.
• site.json has errors or Couldn’t read your repo - these block Next. Fix the file, or the repository connection, and try again.

Branding

Preset themes help you decide the base look and feel of your Site. Once selected, you can override colors, logos, fonts, header links, and footer on the Branding tab after creation.

Access

Restricted (auth-required) Sites show a sign-in banner on every page, controlled by a toggle that is on by default. Public Sites have no sign-in banner.

Click Create Site. Jolli builds the initial version, provisions hosting, and deploys. Status moves from Publishing… to Up to date; click the external-link icon to open it.

The Site detail view

Opening a Site gives you two views in the left nav, Content and Branding, grouped under a Site heading. Content opens first. Settings is the button at the foot of that nav and opens a separate page holding the Site’s information and statistics, the domain, access, schedule, and Danger Zone. Branding is covered below.

Changing what the Site includes

The Content tab is where you revisit the choices you made in the wizard’s Content step. It has two parts.

Articles. The same picker as the wizard: Include all articles, or an explicit selection with search and select-all. Changes here are not live until you click Save Selection - the button reads No changes until you have made one. Removing an Article from the selection takes it off the Site on the next publish; it stays in the Space untouched.

Space. You can point the Site at a different Space from here. Jolli warns first that changing the Space will clear your current Article selection, which it will - the selection belongs to the old Space’s Articles and does not carry over.

On a git-backed Site the tab is there but has no controls. It shows a Managed by site.json notice naming the connected repository and branch, because the repository decides both what is included and how it is arranged.

Theme packs

The Branding tab leads with a theme pack - the overall look and layout your Site is built on. Pick one from the preview cards, then fine-tune colors, typography, logo, and navigation in the sections below. Two built-in packs ship today - Forge and Atlas - and more may be available from the theme registry.

Git-backed Sites take their branding from the connected repo, so the Branding tab is read-only for them.

Upgrading from Classic (one-way)

Older Sites may still be on the Classic pack, which carries extra Layout and Navigation controls. Selecting a built-in pack (Forge or Atlas) on a Classic Site is a one-way upgrade:

• A confirmation dialog shows which pack you’re switching to before anything changes.
• Confirming restyles the Site and drops the Classic-only Layout and Navigation settings. There is no way back to Classic once you upgrade.
• A Classic Site can’t jump straight to a registry theme - upgrade to a built-in pack first, then pick a registry theme from the normal picker.

Branding changes, including a pack upgrade, take effect on the next publish.

site.json, for Sites backed by a repository

When a Site’s Space is backed by a git repository, a file named site.json at the root of your docs folder controls the Site’s title, navigation, and look. This is why the Branding tab is read-only for those Sites: the repository is the source of truth, so you change branding by editing the file and publishing, not in the app.

A published Site needs a title, a theme, and navigation. A description is optional, and worth setting anyway:

{
  "title": "Orbit SDK Docs",
  "description": "Guides and API reference for the Orbit SDK.",
  "theme": { "pack": "forge" },
  "navigation": [
    {
      "group": "Get started",
      "content": [
        { "article": "Introduction", "href": "/introduction" },
        { "article": "Install", "href": "/install" }
      ]
    },
    { "article": "Authentication", "href": "/api/auth" }
  ]
}

Note the shape of navigation: a group’s content is a list of entries, not a path. Each entry is an article with an href.

The fields you will use most often:

• title and description - shown in the browser tab and the header, and used for the llms.txt heading.
• theme - the theme pack and its overrides: pack, primaryColor, logoUrl, favicon, defaultTheme, fontFamily.
• navigation - the sidebar and any navbar tabs. Entries are pages, groups, or articles.
• header and footer - navbar items and dropdowns, and the footer’s copyright, link columns, and social links.

The two places site.json is read are not identical

The same filename is used by the hosted Site and by the jolli site commands you run on your own machine, and they do not accept exactly the same file. A file that builds locally can be rejected when you publish, and the reverse.

The differences worth knowing:

• The hosted Site requires both theme and navigation. A local build treats them as optional.
• The hosted Site accepts the Forge and Atlas theme packs. A local build also accepts default, and Classic is not accepted by either; a Classic Site upgrades through the app first.
• The hosted Site is strict about the contents of theme, header, and footer: a misspelled field inside one of them makes the whole file invalid. A local build ignores fields it does not recognize, so the same typo silently does nothing.

A rejected site.json does not fail the build

This is the part worth knowing before you go looking for an error that isn’t there. When the hosted Site can’t validate your site.json, it publishes anyway. The file is discarded whole, navigation is regenerated from your folder structure, and the title falls back to the Space’s name. The Site’s status reads Up to date, because from the build’s point of view nothing failed.

What you get instead of an error is a single warning line in the build log, naming the field that failed and saying navigation came from the directory structure. A missing site.json behaves the same way, with an informational line rather than a warning.

So the symptom to recognize is not a build failure. It’s a Site that published successfully with the wrong navigation, the wrong title, and none of your branding. If that happens, open the build log and read the warning line - it names the field. One typo inside theme is enough to cost you the entire file.

The creation wizard is the one place that does stop you: it checks site.json before letting you continue, and a file it can’t read or can’t validate blocks the Next button there.

Tweaking branding after creation

The Site detail view’s Branding tab handles post-create edits. Changes apply on the next publish.

• Default theme - Light, Dark, or System.
• Typography - The font style that your Site uses
• Accent color - pick from preset swatches, a color picker, or a hex value. Drives headings, links, and primary actions.
• Logo URL - PNG, SVG, or WebP. Around 400px wide for retina.
• Favicon URL - ICO, PNG, or SVG; 32×32 or 16×16.

Logo and favicon are URL-based, not uploaded - you provide a publicly accessible URL Jolli fetches at build time.

Header navigation

Add up to 6 top-level header items beyond the auto-generated content tree. Each item is either:

• A Link - label + URL.
• A Dropdown - label + up to 8 child links.

Use it for things that don’t belong in the navigation tree itself - Pricing, Changelog, your main marketing site, an external GitHub link.

Footer

• Copyright line - up to 200 characters.
• Up to 4 columns, each with a title and up to 10 links. Group resource links however you like.
• Social links - GitHub, Twitter/X, Discord, LinkedIn, YouTube, and Bluesky. Each renders in the footer.

Custom domain

Every Site gets a sitename-account.jolli.site URL by default. Point your own domain at it under Site Settings → Custom Domain. Each site supports one custom domain.

You can add a subdomain (docs.yourdomain.com) or an apex (yourdomain.com). Each needs a different DNS record type.

Subdomain - CNAME

Field names vary by provider - Host may be called “Name,” Value may be called “Target.”

Apex - A

Apex domains don’t support CNAME at the top level. If your DNS provider supports ALIAS, ANAME, or flattened CNAME at the apex (Cloudflare and a few others), follow their guidance. Leave TTL at the provider default.

Verify ownership (TXT)

Some domains need a second record to prove ownership - usually an apex domain, or one already in use on the hosting side. When Jolli shows a Verify domain ownership step with a TXT record, add that record too, alongside the CNAME or A record above. If no TXT step appears, none is needed.

Verification

The domain enters the list as Awaiting DNS. While any domain is pending, Jolli auto-checks the DNS record. When the record matches, the status moves to Connected. If it doesn’t match, the status shows Check DNS - usually a wrong record type, an existing conflicting record, or a DNS-provider quirk (Cloudflare’s proxy mode, for instance, can change CNAME resolution). Click Verify to force an immediate re-check.

DNS propagation usually takes 30 minutes or less; rarely several hours.

To remove a domain, find it in the list and click Remove. Jolli stops serving the Site at that domain immediately. Re-adding requires re-verifying DNS.

A domain points at exactly one Site. Use subdomains (docs., help.) to host multiple Sites under the same root.

Publishing

Each Site shows a status indicator:

• Up to date - live Site matches current Articles.
• Publishing… - rebuild in progress.
• Pending Changes - unpublished edits in the Space; click Publish to catch up. The panel names what is waiting, which includes an edited Site Summary and out-of-date Search Engine Files as well as article changes.
• Build error - last build failed; click for logs.

Manual publish

Click Publish in the Site header. Jolli rebuilds from the current Space state and deploys.

While a site is building, the indicator shows a live progress percentage that updates as the build proceeds. If you started it by mistake, click Cancel Build to stop the build.

Auto-publish schedule

Under Site Settings → Auto-Publish Schedule, tick Enable auto-publish, set the interval and time of day on the Every … day(s) at … row, and Save. A Times shown in … note names the timezone, read-only from your profile.

Scheduled builds run on the cadence you set, regardless of whether anything changed - each run regenerates and republishes the Site. Pick a low-traffic hour and a sensible interval so you aren’t rebuilding more than you need.

Publish on branch update

For a Site whose Space is backed by a git repository, Site Settings → Publish on Branch Update republishes the Site automatically whenever its watched branch is updated. Turn on Enable publish on branch update, and the panel shows which branch is being watched. Unlike the schedule above, this fires on a push rather than on a clock.

Source-driven publishing

If the Site’s Space has connected Sources, Gap Analysis can trigger rebuilds when tracked code changes. A push lands → Gap Analysis proposes a Changeset → auto-apply (if on) applies it → Pending Changes appears → the next auto-publish or manual click rebuilds.

Auto-apply is on for a new shared Space, whose repository Jolli manages, and off for a Space you bound to your own repository. See The Jolli Agent.

Build errors

Common causes of build failures include:

• Malformed Markdown - usually an unclosed code fence or HTML tag. The build log names the article and line.
• Invalid OpenAPI spec - JSON or YAML parses but is missing required fields (openapi/swagger, info.title, info.version, paths). (Both JSON and YAML are accepted; no conversion needed.)
• Broken image references - an image URL in an article isn’t reachable from the build environment.

(A Space with no published Articles is not a build error - it builds a placeholder page.)

Every failure produces a plain-English What Happened summary plus the last 500 lines of raw build logs. Open the build error from the changes indicator at the top of the Site detail view.

AI discovery (llms.txt)

Every published Site automatically generates two plain-text files at its root for AI clients (Claude, Cursor, ChatGPT, and others) to ingest:

• /llms.txt - a titled, sectioned index of the Site’s pages, each with its link and a short description. Sections follow your navigation and folder structure; OpenAPI specs are grouped under an API Reference section.
• /llms-full.txt - the full prose corpus: every page’s Markdown body concatenated into one document.

Both are written on every publish - for git-backed and managed Sites alike - and every page advertises them in its HTML <head> (<link rel="alternate" type="text/markdown" href="/llms.txt">) so AI clients can discover them automatically.

Page descriptions come from each Article’s frontmatter description:, falling back to its first paragraph. To ship your own version of either file, commit an llms.txt or llms-full.txt at your docs root - Jolli passes an author-provided file through untouched. A very large llms-full.txt (roughly 2 MB or more) still builds but logs a size warning, since a big corpus can slow AI ingestion. On a Restricted Site, both files sit behind the same sign-in gate as the rest of the Site.

/llms.txt is written for an agent arriving with no other context, so a few things are deliberate:

• Links are absolute. Page links and the Source: line under each entry carry the full URL, so an agent that reads the file on its own can follow them without knowing where it came from.
• Cross-references between your articles resolve to real URLs. A link written as a jrn: reference in one article points at the other article’s published page rather than at an internal identifier.
• Sections follow your navigation. Headings come out in the order your Site’s navigation defines, instead of alphabetically by slug, and each page contributes a single heading.

Give your Site a summary

Site Settings → Site Description takes a one-line summary of what the Site covers. It opens /llms.txt, so an agent knows what the Site is before it reads a single page.

The field’s own help text says it plainly: published to /llms.txt on the next publish. Editing the summary does not change the live Site on its own - it shows up under Pending Changes as Site Summary until you publish.

robots.txt and sitemap.xml

Every published Site also serves the two files search engines look for.

• /robots.txt is always written. On an open Site it allows crawling, points at /sitemap.xml once the Site has a web address, and names /llms.txt in a comment so an agent fetching the first file finds the second.
• /sitemap.xml lists every page of the Site, and is written once the Site has a canonical web address. Before a domain is attached there is no address to build absolute links from, so no sitemap is produced - attach a domain and republish.

A Site behind a sign-in is treated differently: robots.txt carries a blanket Disallow: /, no sitemap is written, and /llms.txt is not advertised. Pointing crawlers at the full contents of a gated Site would defeat the gate.

A very large sitemap (above 50,000 URLs) still builds, with a warning in the build log - search engines may ignore the overflow.

If a Site was published before these files existed, or published before its web address was assigned, that shows up under Pending Changes as Search Engine Files. Republishing regenerates them.

Ask the Agent to manage your Sites

The Jolli Agent can do most Site work for you from a conversation: create a Site, publish or republish one, change its display name, source Space, or article selection, list your Sites, check a build’s progress, and crawl an existing public docs site to import its pages into a Space. Ask in plain language, for example “publish the docs site” or “import the pages from docs.example.com”. Creating and editing Sites this way needs the same permission as doing it by hand.

Site search

Every published Site ships a full-text search index, built at publish time from the pages you selected. No setup and no third-party service.

Browse and edit the backing repository

On a git-backed Site, Repository Contents shows the files behind it. You can pick a Branch, see when it was Last synced, and run Sync Now. It is a working file manager, not just a viewer.

Files and folders. Right-click a folder for New Folder, Rename Folder, and Delete Folder - deleting one takes everything inside it, and Jolli says so when the folder isn’t empty. A file’s menu has Move to…, which asks for a destination folder. New File is restricted by location: at the root you may only add Nextra config files and pick from a list of the ones you don’t already have, and inside a content folder you add a _meta file, one per folder. Files Jolli generates are marked Read only - managed by Jolli.

Editing is staged, not immediate. Changing a file marks it Change staged - click Save to commit. Nothing reaches the repository until you press Save; Discard throws the edit away. Because a save is a commit, treat it as one.

Syntax errors block the save. Jolli checks the file as you type and lists what it finds in an Issues panel, counting errors and warnings, including two consistency checks against _meta.ts: an entry with no matching Article file, and an Article file not listed in _meta.ts. While an error stands, the save button reads Cannot save: fix syntax errors first, and Jolli also stops you switching files until it’s resolved. Format tidies the file up.

Custom scripts and styles

To add analytics, a chat widget, or CSS that the branding settings do not cover, commit .js or .css files to a .jolli/scripts folder in the connected repository. Jolli injects them into every page on the next publish. Up to 20 files, each up to 64 KB.

Delete a Site

Deleting a Site is permanent. It lives in a Danger Zone at the bottom of Site Settings, available once the Site has finished its first build (its status is live or shows a build error).

• Under Delete this site, click Delete. An inline confirmation appears with a warning that the action can’t be undone.
• Click Delete Permanently to confirm, or cancel to back out. While the delete runs, the button shows a deleting state.

Deleting a Site removes the published website and stops serving it. The Space it was built from - and all its Articles - are untouched; you can build a new Site from the same Space later.

Next steps

• Spaces - where the content actually lives.
• Editing & Organizing - the writing surface.
• The Jolli Agent - the AI agent and review flow that produces what gets published.