unify preview for VS Code

See a unify page, layout or include rendered while you edit it, beside the editor.

The extension is a thin frame on unify dev. The server composes, maps and reloads; the extension starts it (or attaches to one you already run), asks its page map which address shows the file in the editor, and shows that address in a panel. Nothing is composed twice and nothing is written to your site.

What you see

A page at its built address, exactly as unify build would publish it.
A layout as itself: includes inlined, slot fallbacks rendered, stylesheets and images resolved from the file that linked them. Choose a page that uses the layout and the panel shows the layout composed with it.
An include on its own, inside the site's <head> and body class but with none of the layout's body, showing its own default content. Choose a page that includes it and its slots fill the way that page fills them; choose a layout to decide which head frames it.

The panel follows the active editor and refreshes after every save, through the server's own reload stream.

Use

Open a folder that holds a unify site (a unify.yaml, or a site/ with a _layout.html). unify 0.10.1 or later must be runnable there: the workspace's own node_modules/.bin/unify, or npx @fwdslsh/unify.
Open any .html or .md file of the site and run unify: Open Preview to the Side (the preview icon in the editor title).
Editing a layout or include, run unify: Choose Page or Layout Context for the Preview to compose it with a page. Only pages that actually use the file are offered; the server knows which ones from the build's own provenance.

Settings

Setting	Default	Meaning
`unify.command`	`""`	How to run unify. Empty means the workspace's `node_modules/.bin/unify` when present, else `npx @fwdslsh/unify`.
`unify.port`	`0`	The port `unify dev` listens on; `0` picks a free one.
`unify.devServerUrl`	`""`	Attach to a `unify dev` you already run, such as `http://localhost:3000`, instead of starting one.
`unify.followActiveEditor`	`true`	Switch the preview to whichever file you are editing.

Commands: Open Preview to the Side, Choose Page or Layout Context, Clear the Preview's Context, Restart unify dev, Stop unify dev, Show unify dev Output.

How it works

Everything comes from two things unify dev serves:

/_unify/pages.json, the page map: every emitted page with its source file, the layout it composed with, the includes it reaches and the address it is served at.
/_unify/preview/<source path>, the source preview: a layout or include rendered on request from the source tree by the build's own inliner, composer and URL rewriting. The extension passes ?config=false and makes the page and layout choice itself, with the same ?page= and ?layout= the server's own corner selector would set.

Open either in a browser without the extension and you have the same preview; the extension adds the editor-following and the quick picks.

Develop

npm install
npm run check      # syntax check and the unit tests for the file-to-address mapping
npm run package    # a .vsix, via @vscode/vsce

Press F5 in VS Code to run the extension in a development host.

Publish

.github/workflows/publish.yml publishes to the VS Code Marketplace and attaches the .vsix to a GitHub release, on a v* tag or a manual run. It uses the Marketplace's trusted publishing (vsce publish --oidc): no token is stored anywhere, and no Azure DevOps account is involved. Once, on the fwdslsh publisher's page at marketplace.visualstudio.com/manage, add a trusted publishing policy for the repository fwdslsh/unify-vscode and the workflow file publish.yml. Then bump version in package.json and CHANGELOG.md, and push the tag or run the workflow. The .vsix the workflow packages can also be uploaded by hand on that same page.

License

MPL-2.0, the same as unify.