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.11.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, pick a page in the selector at the bottom of the panel, or run unify: Choose Page or Layout Context for the Preview (the list icon in the panel's title bar). 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 server's corner selector shows in the panel too, and the extension's quick picks set the same ?page= and ?layout=.
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
Bump version in package.json and CHANGELOG.md, then push a v* tag or run the Release workflow (.github/workflows/publish.yml). It checks, packages, and creates a GitHub release carrying the .vsix. Upload that .vsix on the fwdslsh publisher's page at marketplace.visualstudio.com/manage: the workflow's Marketplace step is switched off until the Marketplace offers trusted publishing for the publisher. The comment at the top of the workflow says how to switch it on when it does (vsce publish --oidc, no token, no Azure DevOps).
License
MPL-2.0, the same as unify.