VS Code extension
Opens .json, .py (Python-repr), .csv/.tsv/.tab, .xml and
.html/.htm files in a VS Code custom editor — the same viewer engine
as the standalone page and the
Python library, rendered as packed spatial boxes
instead of an indented tree. Everything the viewer itself does — hover
hints and the interpreter panel, link previews, the nested-container
limit, the [?] popover with its keyboard shortcuts — works here too;
this page covers only what's specific to VS Code.
It is not registered as the default editor for those extensions
(.py in particular is obviously source code most of the time) — you
open it explicitly, per file.
Install
Not yet on the VS Code Marketplace — install the .vsix manually:
- Download structile.vsix.
- In VS Code: Ctrl+Shift+P -> Extensions: Install from VSIX...
- Pick the downloaded file.
To update later, download a newer .vsix from this page (when one is
posted here) and repeat step 2 — VS Code replaces the old version. What
changed from release to release is in the version history.
Opening a file with the viewer
Replace the current tab (Open With… / Reopen Editor With…):
- Find the file in the Explorer sidebar, or in an already-open tab.
- Right-click it and choose Open With… (not currently open) or Reopen Editor With… (already open as text).
- Pick Structile from the picker.
Or from the command palette, with the file already open: Ctrl+Shift+P -> Reopen Editor With… -> Structile.
Keep the source open and add the viewer beside it — the equivalent of VS Code's own Markdown: Open Preview to the Side: with one of those files open as text, press Ctrl+K V, use the preview icon at the top-right of its editor tab, or Ctrl+Shift+P -> Structile: Open Preview to the Side. The source stays where it is and the viewer opens in the column beside it, with two-way sync between them.
Selection, collapse/fold, and edits stay in sync
With the source open beside the graph (Open Preview to the Side),
.json/.py/.csv/.tsv files always stay synced in both directions,
live; an interpreter-backed file syncs too whenever its interpreter opts in
(see Writing and distributing
interpreters — the bundled XML/HTML
interpreters do, except the deliberately non-syncing comparison
variants). An interpreter that doesn't opt in
leaves sync graph-only for that file, same as before this existed:
- Clicking a key/value in the graph selects and scrolls to the matching text in the real editor; placing the cursor or selecting text in the real editor highlights the matching node in the graph.
- Collapsing/expanding a dict or minimizing a table in the graph folds/unfolds the matching region in the real editor (VS Code's own code folding); folding/unfolding a region in the real editor collapses/expands the matching node in the graph. The real-editor -> graph direction only sees folds within the current viewport — a VS Code API limitation, not a bug.
- Renaming a key/name/column in the graph commits immediately and is mirrored straight into the real editor's buffer, live. Editing a value in the graph opens the familiar inline popup as an Edit-review session (original vs. your edit, with its own Save/Cancel) — it only reaches the real editor once actually saved. Typing directly in the real editor reaches the graph the other way: a moment after you stop typing, the graph rebuilds to match, keeping whatever's currently collapsed as-is, with dirty-dot markers for exactly what changed.
- Saving works from either side and finalizes both — Ctrl+S with focus in the real editor, or the graph's own Save button next to Undo/Redo (the standalone viewer's Save/Save As… buttons are hidden here, since this editor always saves through VS Code's native command). A save writes only what you changed: comments, quoting and the way numbers are written stay as they were (a TOML, YAML or INI file saved through its interpreter changes only the edited lines), and the file's Windows line endings and UTF-8 byte-order mark are kept — a JSON file that starts with that mark opens normally too. Undo and redo in the graph put back the file's exact text.
Opening other file extensions
Only .json/.py/.csv/.tsv/.tab/.xml/.html/.htm are wired
up out of the box. To open a different extension with this viewer — say,
a .cfg file that's actually XML underneath — two settings work
together, in your User or Workspace settings.json (Ctrl+Shift+P ->
Preferences: Open User Settings (JSON)):
"workbench.editorAssociations": {
"*.cfg": "structile.editor"
},
"structile.extensionFormats": {
".cfg": "xml"
}
The first (a built-in VS Code setting) tells VS Code which editor to open
that glob pattern with; the second tells the extension itself which
format that file actually is — one of json, python, csv, xml,
html or bin (see Binary formats below).
XML via an interpreter
XML isn't a fixed schema — the viewer needs a small caller-supplied JavaScript interpreter script to say what the tags and attributes in a given file actually mean. See Writing and distributing interpreters for the full guide; two ways to attach one to a file here, checked in order:
- A sibling file:
config.xml->config.interpreter.jsright next to it. Wins outright if present. - The
structile.interpretersetting, as a fallback — a single path or an array of candidates tried in order:
Set it at the User level (not Workspace) to apply across every
project you open, not just the one whose settings.json it's in — see
"Shipping interpreters for a whole team" below.
Neither present -> the file still opens, with a warning, and waits for one.
Binary formats
An interpreter that reads bytes rather than text declares
"format": "bin" — in a contributes.structileInterpreters entry (see
Shipping interpreters for a whole team
below), or, for a sibling <name>.interpreter.js / a structile.interpreter
script / a workspace mapping, by pinning the extension to bin first,
since those three otherwise always mean the XML contract:
(plus the matching workbench.editorAssociations entry, as for any
non-built-in extension). The script's interpretText(text) receives the
file one character per byte — text.charCodeAt(i) & 0xff is byte i —
never decoded and never line-ending-normalized, and the file opens
read-only: there is no way back from the interpreted view to the
bytes, so there is nothing to save. Structile: Show Interpreter
Resolution reports which candidate read it, as for any other format.
It's the same contract the standalone viewer's bundled binary
interpreters use, so one script serves both — see
the interpreters guide.
Interpreter panel and hover hints
Whenever an interpreter read the file, the viewer's header shows the puzzle-piece button (tooltip: "Interpreter: details and options") here too. Its panel names the interpreter and its version, says where it came from, what it can do, and shows the interpreter's own options as live controls — plus Show hints in cells, which writes an interpreter's hover hints after each value. Hovering a value shows those hints in its tooltip, as in the standalone page. The panel also says whether the values are remembered for every file that interpreter reads or kept for this document only. See Hover hints and interpreter options for what an interpreter has to declare.
Shipping interpreters for a whole team
The structile.interpreter setting above already covers most of this:
set it once at the User level, in your own VS Code profile, and it
applies in every project you open from then on — nothing committed to
any repo, no extension to build. A wiki page with the interpreter .js
file attached and that JSON snippet to paste is the whole "distribution"
story for most teams. See
Writing and distributing interpreters
for the two heavier options past that point (a trusted-workspace-only
project folder, for a format that genuinely belongs to one repo; a VS
Code extension contribution, for an organisation that already ships
internal extensions), plus Structile: Show Interpreter Resolution and
Structile: List Contributed Interpreters for debugging which source
actually won.
Settings
Everything lives under structile.* in your User or Workspace settings
(the Settings UI lists them under Structile; leaving one null keeps
the viewer's own default, shown in each description):
| Setting | What it does |
|---|---|
structile.theme |
auto (default), light or dark. |
structile.nameMax, .valMax, .headerLabelMax |
Characters before a key / value / outer title is truncated (14 / 14 / 32). |
structile.n, .m, .N, .M, .detCols, .detRows, .kvRows, .kvCols, .gap, .dwellMs, .maxWidthFrac |
The packing layout: compact and expanded table sizes, detached-table limits, values per column before wrapping, columns before expand/detach, box spacing, hover-peek delay, box width cap. |
structile.cellContainerBadges |
A dict/table held by a table cell as a clickable {n}/[n] badge that opens it beside the table (on by default); off shows the cell's raw JSON text. |
structile.limitChildren, .childCap, .childStep |
Show only the first childCap (20) nested dicts/tables of each dict behind a "k of n hidden" banner (on by default), and how many more each "show more" click adds (100). |
structile.drawAllBoxes, .warnElements |
Draw every box of a big view at once, also those far off screen (off by default — a view of more than 400 boxes otherwise draws only what's near the window), and the page-element count above which a redraw warns (20,000; 0 = never). |
structile.loadNoticeSec, .loadConfirmSec |
Show "Loading…" when a load should take longer than this many seconds (1), and ask first above this many (10); 0 turns either off. |
structile.forNull, .forEmpty, .values |
Display overrides for null, empty containers and exact strings — cosmetic only. |
structile.linkOpen, .linkClose |
The prefix/suffix that makes a value a clickable link to the same-named dict/table elsewhere in the document (off until set). |
structile.interpreter, .extensionFormats, .viewerHtmlPath |
The interpreter fallback path(s), extra extension → format mappings (json, python, csv, xml, html, bin), and where to find the viewer HTML when the extension isn't running from a repo checkout. |
Set as default at the bottom of the viewer's own Settings panel writes the panel's current values into these settings — Workspace scope when a workspace is open, otherwise User scope, with a notice saying which — so every view opened from then on starts with them.
Known limitations
- Only one viewer panel per document — opening the same file a second time refocuses the existing one.
- VS Code's own Ctrl+Z won't step through individual edits made inside the graph — use the graph's own Undo/Redo while focus is inside it.
- A graph edit mirrors into the real editor as a whole-document replace, not a targeted splice — expect its cursor position/scroll to jump on every graph-side edit.
structile.extensionFormatsdoesn't extend Open Preview to the Side's own keybinding/menu entries — those stay scoped to the built-in extensions above; use Reopen Editor With… for a custom-mapped one.