Live Docify VSCode Plugin

[LeighFinegold]

Target Project:

calm-vscode-extension (or the VS Code plugin portion of the CALM monorepo)

Description of Feature:

We would like the Docify VS Code extension to support live rendering of templates and architecture models. Currently, when working with Handlebars templates or CALM JSON/YAML models, users have to manually trigger a render, and the results sometimes appear in separate untitled Markdown documents or in multiple preview tabs. The feature should aim to provide a smoother, always-available preview experience inside VS Code, similar to how Markdown Preview works but tailored to Docify.

User Stories:

• As an architect, I want to edit a Handlebars template and see the rendered output update automatically, so I can iterate quickly without repeatedly running commands.
• As a developer, I want to open a CALM architecture model and understand its rendered form immediately, so I don’t lose context between code and output.
• As a user, I want the preview to be clear and consistent, without confusing tab names or multiple previews, so I know exactly where to look for results.

Current Limitations:

• The experimental plugin Experimental: VScode plugin #1516 showed a baseline of tooling that will aid a user to see how changing their calm content. The plugin lacks though the ability to aid in a calm documenter to leverage the widgets provided by calm-docify to streamline creation of architecture documentation artefacts.

• With the intro of --scaffold mode with calm docify --website mode, we want users to be able to change the default generated website with confidence

Proposed Implementation:

At this stage, the implementation approach is not fully clear. Possible directions include:

• Investigating whether the preview should be handled entirely within our own webview (so we can control the title and behavior).
• Deciding how the preview should update: on save, on every keystroke (debounced), or only when a command is run.
• Determining if templates and models should share a single preview tab or if each should have its own.

Testing Strategy:

We would need to test:

• Editing a template and seeing the preview update.
• Editing a model and seeing the preview update.
• Switching between files and ensuring the preview follows correctly.
• Validating Mermaid diagrams and Markdown render consistently.
  Tests would likely be a mix of unit tests around parsing/invocation and integration tests in the VS Code extension environment.

Documentation Requirements:

• Update the extension README with details on how live preview works.
• Document any limitations (e.g., whether it updates on save vs. typing).
• Provide example workflows (editing a template, editing a model, expected preview behavior).

Implementation Checklist:

• Decide on preview strategy (webview vs. Markdown Preview).
• Design approved.
• Implementation completed.
• Tests written and passing.
• Documentation updated.
• Assess performance and usability.

Additional Context:

Users often expect a live preview to behave like the built-in Markdown Preview: always available, predictable, and without extra files opening. Currently, the mix of approaches (untitled Markdown docs, built-in preview, inline rendering) is inconsistent and confusing. A unified live preview solution would make the extension much more intuitive.

[LeighFinegold]

Agreed on #1622 to publish an alpha version of the plugin as demoed on LeighFinegold#20.

LiveDocifyVSCodePlugin.mov

[LeighFinegold]

With the initial plugin published to the VSCode marketplace, closing this issue and await feedback

https://marketplace.visualstudio.com/items?itemName=FINOS.calm-vscode-plugin