Skip to content

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:

  1. Download structile.vsix.
  2. In VS Code: Ctrl+Shift+P -> Extensions: Install from VSIX...
  3. 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…):

  1. Find the file in the Explorer sidebar, or in an already-open tab.
  2. Right-click it and choose Open With… (not currently open) or Reopen Editor With… (already open as text).
  3. 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.

The Structile custom editor open on a JSON file, real source on the left and the packed-box graph on the right — a gamma value is selected in the source and the matching cell is highlighted gold in the graph, showing the two-way sync described above Hover for the other theme

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:

  1. A sibling file: config.xml -> config.interpreter.js right next to it. Wins outright if present.
  2. The structile.interpreter setting, as a fallback — a single path or an array of candidates tried in order:
"structile.interpreter": [
  "interpreters/schema_a.js",
  "interpreters/schema_b.js"
]

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:

"structile.extensionFormats": { ".abf": "bin" }

(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.extensionFormats doesn'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.