MarkVSpec VS Code Extension
MarkVSpec provides live preview, diagnostics, and syntax highlighting for
.vspec.md screen specification files.
Get Started
Open a .vspec.md file, then open the preview from one of these entry points:
- Run
MarkVSpec: Open Preview from the Command Palette.
- Click the preview icon in the editor title.
- Right-click the file in Explorer and select
Open Preview.
The preview updates as the document changes. Parser diagnostics are also
published to VS Code Problems for .vspec.md files. The preview toolbar
shows the rendered file path so the current target is visible when switching
between MarkVSpec files.
Use MarkVSpec: Export Static HTML to write a standalone HTML file for the
active MarkVSpec document. Use MarkVSpec: Export PDF when you need a PDF.
For current preview/export limitations, including PDF export requirements, see
Known limitations.
Bundled Examples
The active examples/ directory is a learning path:
examples/01-basics/hello-screen.vspec.md is the smallest useful document.examples/04-real-world-screens/login-basic.vspec.md covers a compact authentication flow with validation feedback scenarios.examples/02-states/async-loading.vspec.md covers request send and response states.examples/02-states/scenario-samples.vspec.md covers Preview Scenario data variations over baseline Element samples.examples/02-states/responsive-profile.vspec.md covers mobile and desktop layouts.examples/03-actions/event-triggers.vspec.md covers non-click events and lifecycle triggers.examples/03-actions/form-submit-flow.vspec.md covers validation, server call, and navigation.examples/03-actions/single-field-validation.vspec.md covers focused single-field validation contracts.examples/03-actions/toast-feedback.vspec.md covers non-modal toast feedback and targetless toast display.examples/03-actions/parallel-initial-load.vspec.md covers parallel server calls and Resolve.examples/04-real-world-screens/notice-detail.vspec.md covers Display Content Spec fields.examples/04-real-world-screens/profile-edit-rich.vspec.md covers extended form, media, list, and dialog element types.examples/04-real-world-screens/search-list.vspec.md covers search, filters, pagination, and table sample rows.examples/05-reuse/template-shell.vspec.md covers template slots.examples/05-reuse/profile-page-with-template.vspec.md covers template composition, route params, partial host metadata, and display.partial refresh.examples/05-reuse/profile-summary.partial.vspec.md covers partial routes and partial-local states.examples/06-structured-sections/history-and-errors.vspec.md covers Error Codes, History Fields, and History.
The active examples use short heading markers such as L1, 1, and A1 for
preview readability; MarkVSpec references still use stable IDs such as
L-LoginPage, E-PageTitle, and A-SubmitLogin.
Local Development
From the repository root:
npm install
npm run build
Then open this repository in VS Code, select Run MarkVSpec Extension, press
F5, and open the preview from the editor title, Explorer context menu, or
MarkVSpec: Open Preview in the extension development host.
To install a locally built VSIX:
npm run package:vsix -w packages/vscode-extension
code --install-extension dist/markvspec-<version>.vsix
Realtime Preview Smoke Check
Use this quick check after changing preview update behavior:
- Open
examples/04-real-world-screens/login-basic.vspec.md.
- Run
MarkVSpec: Open Preview.
- Open the
MarkVSpec output channel.
- Toggle Layout, Element, and Action markers and confirm marker labels remain
readable in the wireframe and generated document.
- Edit an existing Element display value, such as a
value: or placeholder:
line, without saving.
- Confirm the preview updates after the debounce window and the output contains
phase=fragment-patch, patchSuccess=true, and patchReason=applied.
- Add or remove an Element or Layout item.
- Confirm the preview still updates and the output contains
phase=full-render
with a full render reason.
Verification
npm run typecheck
npm test
npm run build
npm run package:vsix -w packages/vscode-extension
