yaml-preview-enhanced-r

A live, searchable preview for YAML files in VS Code — a collapsible tree, a readable document view with Markdown and inline PlantUML diagrams, JSON Schema validation, themes and export.

Introduction

yaml-preview-enhanced-r brings the Markdown Preview Enhanced experience to .yaml and .yml files. Open a preview next to your editor and the extension:

• shows the file as a collapsible tree with types, anchors, aliases, comments, line numbers and automatic tables;
• reads it as a document — titles become headings, metadata collapses, text is rendered as Markdown and PlantUML diagrams are drawn inline;
• converts it to JSON or resolved YAML (anchors, aliases and merge keys expanded);
• validates it against a JSON Schema and lists YAML and schema problems;
• keeps the editor and the preview in sync as you type, scroll and click;
• exports to HTML, PDF, PNG, JPEG, JSON, resolved YAML and Markdown.

It works for plain YAML and for the formats built on it: Kubernetes, OpenAPI, Docker Compose, GitHub Actions, Ansible, Azure Pipelines, Home Assistant, CloudFormation and more.

Requirements

Installation

Install the packaged extension from a .vsix file:

code --install-extension yaml-preview-enhanced-r-0.1.2.vsix

Or in VS Code: Extensions view → … menu → Install from VSIX….

To build the .vsix yourself, see Development.

Getting Started

1. Open a YAML file (.yaml or .yml).
2. Open the preview — it does not start on its own unless you turn on automaticallyShowPreviewOfYamlBeingEdited. Use any of these:
   • press ctrl-k v (cmd-k v on macOS) to open the preview to the side;
   • click the preview icon in the editor title bar;
   • right-click the editor and choose yaml-preview-enhanced-r: Open Preview to the Side;
   • run yaml-preview-enhanced-r: Open Preview from the Command Palette.
3. Pick a view in the preview toolbar: Tree, Document, JSON or Resolved.

To open every YAML file straight into the preview instead of a text editor, set yaml-preview-enhanced.previewMode to Previews Only. You can also choose Reopen Editor With… → YAML Preview for a single file.

Try it on examples/requirements.yaml: open it, switch to the Document view, and the requirement text and the sequence diagram are rendered inline.

Views

The toolbar also offers Expand, Collapse, an expand-to-level selector, a search box, and the toggles Tables, Comments, Sort (none → A→Z → Z→A) and MD (Markdown rendering in strings: off → by key → all). A status area shows the node count and the number of problems and warnings; click it to jump to the first problem. Files with several --- separated documents get one tab per document.

Everything the preview does is display-only — your file is never modified, except when you explicitly run Associate JSON Schema…, which inserts a # yaml-language-server: $schema=… comment.

Document view

The Document view turns a data file into something you can read. Which keys play which role is configurable.

Everything else is shown as key value lines, sub-headings or tables. Settings: documentTitleKeys, documentMetadataKeys, documentTextKeys, documentFlattenKeys.

- id: req:user-login
  type: requirement
  metadata:
    status: approved
    owner: web-team
  text: |
    A registered user shall be able to sign in with an e-mail address and a password.

Inline PlantUML Diagrams

PlantUML diagrams are rendered locally with java -jar plantuml.jar -pipe -tsvg. A diagram can appear:

• as an @startuml … @enduml block (or any @start<kind> … @end<kind>, such as mindmap, gantt, salt, wbs) inside a string value;
• as a ```plantuml (or puml, uml) fence inside Markdown text;
• as the value of a key listed in plantumlKeys (default plantuml, puml, uml) — @startuml and @enduml are added for you.

- title: Sign-in flow
  plantuml: |
    @startuml
    actor User
    participant "Web App" as App
    User -> App: submit(email, password)
    App --> User: show dashboard
    @enduml

Setup

1. Install Java and download plantuml.jar.
2. Set yaml-preview-enhanced.plantumlJarPath to the jar (default /usr/local/bin/plantuml.jar). If java is not on your PATH, also set yaml-preview-enhanced.javaPath.
3. Run yaml-preview-enhanced-r: Test PlantUML Setup to confirm it works.

Diagrams are cached, rendered in parallel (a bounded number at a time) and stopped if they exceed plantumlTimeoutMs. Run Clear PlantUML Cache and Refresh Diagrams after changing PlantUML settings or the jar. Right-click a diagram to enlarge it, copy its source or save it as SVG.

Security

A YAML file you open may be untrusted, so diagrams run with PLANTUML_SECURITY_PROFILE=SANDBOX by default: they cannot read local files or use the network. The bundled standard library (!include <C4/…>) still works. Change plantumlSecurityProfile to INTERNET, LEGACY or UNSECURE only if your diagrams !include other files.

Diagrams are displayed as images, so a diagram cannot run scripts in the preview. The Java and PlantUML settings are machine-scoped and are ignored in untrusted workspaces. PlantUML is not available in VS Code for the Web.

JSON Schema Validation

Schema problems are listed in the preview, flagged on the offending nodes and, with publishDiagnostics, shown in the Problems panel. A schema is chosen in this order:

1. A modeline comment in the file: # yaml-language-server: $schema=./schemas/ci.json
2. The yaml-preview-enhanced.schemas map of schema path → glob pattern(s), for example { "schemas/ci.json": ".github/workflows/*.yml" }
3. The single yaml-preview-enhanced.schema setting

Schemas may be JSON or YAML, and relative paths resolve against the file (modeline) or the workspace folder (settings). Drafts 2020-12, 2019-09 and 07 are supported, with standard string formats; a schema that declares an older draft is validated on a best-effort basis. Run yaml-preview-enhanced-r: Associate JSON Schema… to pick a schema and insert the modeline for you.

Previewing a file never makes a network request by itself: http(s):// schemas are downloaded only after you enable yaml-preview-enhanced.allowRemoteSchemas.

Search and Navigation

• Search keys and values with the toolbar box (/); step through matches with enter / shift-enter.
• The outline sidebar lists the top-level keys (or the titled blocks in the Document view) and every anchor with the number of aliases that use it.
• Click a line number or double-click a node to reveal its source line in the editor; clicking a problem jumps to it.
• Scroll sync keeps the editor and the preview aligned in both directions (scrollSync). Sync Preview with Editor re-aligns them on demand.
• A locked preview stays on one file while you edit others.
• Right-click inside the preview for a context menu: copy the path, JSONPath, JSON pointer or the value as JSON or YAML, reveal in the editor, expand or collapse children, work with diagrams, and export.

Keys inside the preview

Hiding Sensitive Values

List regular expressions in yaml-preview-enhanced.maskKeys and the values of every matching key are replaced with •••••• in the preview and in exports — handy when sharing your screen:

{ "yaml-preview-enhanced.maskKeys": ["password", "secret", "token"] }

Matching is case-insensitive.

Markdown, Links and Images

• Set renderMarkdownInStrings to byKey (only the keys in markdownKeys, such as description) or all (every multi-line string) to render Markdown inside string values. The Document view always renders its text keys as Markdown.
• URLs in strings become links (enableLinkify). Only the protocols in protocolsWhiteList can be opened from the preview.
• String values that point to images show thumbnails (imagePreview): local (default) loads workspace images only, all also loads remote https:// images, off disables thumbnails. Click a thumbnail to enlarge it.

Exporting

Run yaml-preview-enhanced-r: Export… (or use the right-click menu in the preview) and choose a format:

Copy Document as JSON and Copy Document as Resolved YAML put the result on the clipboard instead. Masked keys stay masked and key sorting is applied in every export.

PDF and image export drive a locally installed Chrome, Chromium or Edge (found automatically; or set chromePath). Inside a container you may need "yaml-preview-enhanced.chromeArgs": ["--no-sandbox"]. Use printBackground to keep background colours in PDFs and exportColorScheme to choose between the selected theme and the viewer's light/dark preference.

Customization

Besides settings, the preview can be customised with four files. Global files live in the config directory (yaml-preview-enhanced.configPath; by default ~/.local/state/yaml-preview-enhanced, or %USERPROFILE%\.yaml-preview-enhanced on Windows) and always apply. Workspace files live in <workspace>/.yaml-preview-enhanced/ and apply on top of them.

Use the Customize CSS, Open Config Script, Extend Parser and Customize Preview HTML Head commands (each in a Global and a Workspace variant) to create and open the files from templates.

config.js and parser.js execute code. Global ones always run; workspace ones run only in a trusted workspace and when yaml-preview-enhanced.enableScriptExecution is on. Customization files are not available in VS Code for the Web.

Commands

All commands are in the Command Palette under yaml-preview-enhanced-r.

Keybindings

The cmd key for Windows and Linux is ctrl. These shortcuts are active in YAML editors (yaml, dockercompose, github-actions-workflow, ansible, azure-pipelines and home-assistant language modes).

Settings

All settings start with yaml-preview-enhanced.. Open Settings and search for yaml-preview-enhanced-r to edit them with descriptions.

Preview behavior

Appearance

Text, links and images

Document view

PlantUML

YAML parsing and schema

Export and customization

Privacy and Security

This extension does not collect, transmit or share your data. There is no telemetry, no tracking and no phone-home.

• YAML content is parsed and rendered locally and never leaves your machine.
• PlantUML runs locally through your own Java and plantuml.jar; no diagram data is sent to any server. Diagrams run in the SANDBOX security profile by default.
• JSON Schemas are read from disk. Remote schemas are downloaded only if you enable allowRemoteSchemas.
• Images: only local images are loaded by default. Remote https:// images are requested only if you set imagePreview to all.
• PDF / image export uses a locally installed Chrome; nothing is uploaded.
• The preview runs under a strict Content-Security-Policy that only allows the extension's own script.
• Untrusted workspaces: settings that point to executables or scripts (plantumlJarPath, javaPath, plantumlArgs, plantumlSecurityProfile, chromePath, chromeArgs, configPath, enableScriptExecution, allowRemoteSchemas) are ignored, and workspace-level scripts never run.
• Virtual workspaces and VS Code for the Web: the preview, schema validation and the HTML, JSON, resolved YAML and Markdown exports work. PlantUML, PDF / PNG / JPEG export, Open in Browser and customization files need the desktop version.

If you have questions about data handling, please open an issue in this repository.

Development

The extension is written in TypeScript and bundled with esbuild. Package management uses pnpm; Node 18 matches the runtime of the VS Code extension host. See AGENTS.md for architecture notes and conventions.

pnpm install            # install dependencies
pnpm build              # bundle to out/ (desktop, web and webview)
pnpm watch              # rebuild on change
pnpm test               # build, then run the mocha tests in test/
pnpm check:all          # ESLint, Prettier and tsc
pnpm package            # create yaml-preview-enhanced-r-<version>.vsix (vsce needs Node 20)

Press F5 in VS Code to launch an Extension Development Host with the extension loaded. After a change, run pnpm build and reload that window (Developer: Reload Window).

Acknowledgements

yaml-preview-enhanced-r is derived from Markdown Preview Enhanced by Yiyi Wang and contributors, and keeps its familiar commands, keybindings and settings style. Many thanks to the authors.

License

University of Illinois/NCSA Open Source License