StrictDoc VS Code Extension

Live preview, traceability validation, navigation, and authoring assistance for StrictDoc (.sdoc) files. The extension pairs syntax highlighting and a webview preview with a Python language server backed by the real StrictDoc engine, so diagnostics and rendering match StrictDoc's own behavior.

Getting Started

Open or create a .sdoc file — the language activates automatically.
Run StrictDoc: Show Preview (or open the Command Palette and search "StrictDoc") to see a live, side-by-side rendering.
On first run the extension provisions a managed Python environment with strictdoc + pygls. If anything is missing, run StrictDoc: Install/Repair Language Server Dependencies.
Edit, save, and watch diagnostics, preview, and navigation update.

No Python setup is required by default. To use your own project venv or a local StrictDoc checkout, see Settings and Runtime Selection.

Features

Live preview — side-by-side webview that updates on every edit. Full-page rendering via the StrictDoc export pipeline, with automatic fragment fallback if export fails.
Bidirectional scroll sync — editor and preview stay aligned via data-source-line mapping.
UID navigation — click a UID in the preview or a StrictDoc UID link in an SVG diagram (including diagrams in lazy-loaded sections) to jump to its .sdoc definition; Go-to-Definition resolves UIDs from RELATIONS VALUE: and inline [LINK: UID] markers across the workspace.
Child relations — show requirements that reference the UID under the cursor and jump to a selected child.
Diagnostics — fast single-document checks on open; full project traceability validation on save (duplicate UID/MID, broken parent/child references, cycles, RST field errors).
Completion — block/field keywords, image directive paths, and next-UID suggestions when typing UID: PREFIX-new.
Hover & outline — UID title and child relations on hover, plus links to .cpp files referencing the UID with @design UID; document symbols/outline for sections and requirements. Source links are scoped to the StrictDoc project (including a sibling Src/ when the configuration lives in docs/) and refresh when .cpp files change.
Folding — block- and field-level folding for requirements and sections.
Directive path links — clickable .. image:: / .. include:: paths that open the referenced file.
Grid table editing — create/convert tables, cell navigation, column resize, and row/column operators (|+, |-, |<, |>, |^, |v) with merge-aware formatting.
Syntax highlighting — TextMate grammar with bracket matching for .sdoc.

Commands

All user-facing commands are available from the Command Palette (search "StrictDoc"). .sdoc commands also appear in the editor context menu. Grid table editing key handlers are hidden from the Command Palette but remain visible in the Keyboard Shortcuts editor.

Command	Description
`StrictDoc: Show Preview`	Open the live preview for the current `.sdoc` file
`StrictDoc: Clear Preview Cache`	Remove cached preview artifacts (`~/.cache/strictdoc-vscode-preview`)
`StrictDoc: Install/Repair Language Server Dependencies`	Install `pygls` into the project venv, or recreate the builtin managed venv
`StrictDoc: Show Child Relations`	List child relations for the UID at the cursor and jump to a selected child
`StrictDoc: Export PlantUML To SVG`	Find all `.puml` files in the workspace and convert them to `.svg` using the configured PlantUML executable
`StrictDoc: Create Grid Table`	Replace a selected `ROWxCOL` marker (e.g. `3x4`) with an empty grid table
`StrictDoc: Convert Selection To Grid Table`	Convert selected CSV-like lines into a grid table
`StrictDoc: Format Current Grid Table`	Reformat the table at the cursor, repairing malformed rows best-effort
`StrictDoc: Format All Grid Tables`	Reformat every grid table in the active document

Keybindings

Editing shortcuts (active in .sdoc files):

Shortcut	Action
`Alt+T`	Convert selected CSV text to a grid table
`Alt+Shift+T`	Format current grid table
`Ctrl+Alt+Shift+T` (`Cmd+Alt+Shift+T` on macOS)	Format all grid tables

Table-aware keys (active only when the cursor is inside a detected grid table):

Shortcut	Action
`Enter`	Move to next row, or execute a row/column operator
`Shift+Enter`	Move to previous row
`Tab` / `Shift+Tab`	Move right / left between cells
`Alt+Enter`	Insert a new content line inside the current cell
`Shift+Alt+Enter`	Insert a new separated row below, preserving merges
`Alt+Left` / `Alt+Right`	Shrink / grow the current column by one character

Navigation keys (Enter, Shift+Enter, Tab, Shift+Tab) only move between cells and never implicitly reformat. Resizing keeps merged cells, headers, and borders consistent so the table stays valid.

Settings

Setting	Type	Default	Scope	Description
`strictdoc.enableLanguageServer`	boolean	`true`	window	Enable the Python language server
`strictdoc.useBuiltinServer`	boolean	`true`	window	Manage a venv in global storage when no project venv is set
`strictdoc.projectVenvPath`	string	`""`	resource	Path to a project venv (e.g. `${workspaceFolder}/.venv`)
`strictdoc.pythonPath`	string	`"python3"`	window	Fallback Python when builtin venv is disabled and no project venv
`strictdoc.sourcePath`	string	`""`	window	Local StrictDoc checkout root (for StrictDoc development)
`strictdoc.serverModule`	string	`"strictdoc_lsp"`	window	Python module that starts the language server
`strictdoc.logLevel`	string	`"info"`	window	Output channel level: `debug`/`info`/`warn`/`error`
`strictdoc.editor.tableEditor.disabled`	boolean	`false`	resource	Disable table commands and keybindings
`strictdoc.editor.tableEditor.reformat.disabled`	boolean	`false`	resource	Disable auto-reformat during table edits

Runtime Selection

The extension resolves the Python environment in this priority order:

Project venv (strictdoc.projectVenvPath) — used directly when valid. It is never mutated automatically; only pygls is added via the repair command.
Builtin managed venv — created in global storage with pinned strictdoc + pygls, recreated when versions change.
Manual fallback — strictdoc.pythonPath is used when both above are disabled/unavailable; you must provide the dependencies.

Troubleshooting

Preview empty or stale: run Clear Preview Cache, then Show Preview.
Diagnostics/preview unavailable: run Install/Repair Language Server Dependencies and check the "StrictDoc" output channel.
Verbose logs: set strictdoc.logLevel to debug.

Attribution

Grid table editing is adapted from the MIT-licensed vscode-restructuredtext project and integrated into this extension.

Development Notes

During local development the extension adds extensions/language-server/src to PYTHONPATH automatically.
STRICTDOC_SOURCE_PATH is passed to the server only when strictdoc.sourcePath is set.
Production deployment uses bundled-server/ (populated by scripts/bundle-server.sh).

StrictDoc Tools

asp