Paligo Theme Studio

Edit a Paligo Nexus theme in VS Code and preview it on real content from your Paligo instance. Paligo renders the preview with the same renderer a publish uses, so what you see is what the published site will show.

What you need

VS Code on the desktop. The extension does not run in VS Code in the browser.
A Paligo instance that supports theme preview.
Your Paligo username and an API key for that user.
A theme folder with a theme.json at its root. The extension starts when you open a folder that contains one.

Getting started

Open your theme folder in VS Code.
Run Paligo: Sign in to instance… from the Command Palette. Enter your instance (a name like acme, a host, or a full https:// URL), your username and your API key. The key is stored in your operating system's keychain, not in VS Code settings.
Run Paligo: Preview theme and choose a publication to preview against.

The preview updates each time you save a file in the theme folder. Links in the preview take you to other pages of the publication.

The first preview of a publication can take a while if the publication has never been published, because Paligo has to build its content first. The pane shows progress while it waits. Later previews of the same publication reuse that content.

Choosing what to preview

The preview's title bar has buttons to refresh it, to choose the publication, the language and the layout to preview with, to push the theme to a layout (see below) and to open the preview in a browser. The layout supplies the site settings, such as branding, search and custom head or body code. The Paligo item in the status bar opens a menu with all the actions.

Previewing in a browser

Paligo: Open preview in browser opens the page you are previewing in a tab of your default browser. It is also a button in the preview's title bar and an entry in the status bar menu. The tab reloads each time you save, and if a render fails, the problem is shown at the bottom of the page over the last one that worked. Cancel and Try again are only in the pane; in the browser, saving a template or running Paligo: Refresh preview tries again.

This works only when VS Code runs on your own computer, not in a remote session. The page is served from your computer at 127.0.0.1, so other machines cannot open it.

If the preview is already open in a tab, the extension asks before opening another one. About two minutes after the last tab is closed the browser preview stops, and running the command again starts it afresh.

For AI agents and scripts

A program that can drive a browser but not VS Code can start the browser preview itself by opening this link, for example with open on macOS:

open 'vscode://paligo.paligo-theme-studio/preview?id=run-1'

The extension then writes .paligo/preview.json in the theme folder:

{ "status": "ready", "url": "http://127.0.0.1:52011/…/", "id": "run-1" }

Open url in the browser. When the preview cannot start, status is error and message says why, such as not being signed in or no publication having been chosen yet. Both have to be done in VS Code first. The id is optional; it is copied into the file so the caller can tell its answer from an older one.

The link goes to the VS Code window used last, so that window needs the theme folder open. The .paligo folder is ignored by git and never pushed to a layout, and the file is removed when the browser preview stops. The file is also written when you open the preview in a browser yourself.

Theme options

The Paligo Theme section in the Explorer lists the options your theme.json declares. Click one to change its value for the preview.

These values only affect the preview. Pushing a theme does not carry them; option values belong to a layout and are set in Paligo. Paligo: Reset theme options to defaults clears them.

Pushing to a layout

The push button in the preview's title bar, or Paligo: Push theme to layout…, uploads the theme folder as the theme of a layout you choose. This replaces the theme on that layout, so the extension names the layout and the theme it uses now, and asks you to confirm before uploading.

Settings

setting	what it does
`paligo.instanceUrl`	Your Paligo instance. Set by signing in.
`paligo.username`	Your Paligo username. Set by signing in. Override it per workspace to work as a different user.
`paligo.caCertPath`	A certificate to trust for an instance that uses a self-signed certificate. Leave empty otherwise.
`paligo.allowedOrigins`	Extra origins the previewed theme may load scripts, styles, images and fonts from, such as a CDN. Empty by default. Add only origins you trust.
`paligo.previewDebounceMs`	How long to wait after the last file change before rendering again. Default 250.

When something goes wrong

Open the Output panel and choose Paligo. It logs when the extension starts, each render, and anything that went wrong. Set the level to Debug from the gear icon for more detail.