english | русский

Diplodoc Extension for VS Code

VS Code extension for the Diplodoc documentation platform. Provides a WYSIWYG Markdown editor, YAML validation, autocompletion, linting, and visual editors for .md, toc.yaml, and page-constructor .yaml files.

Telemetry

Builds configured with a telemetry endpoint send feature-use events and classified errors to Yandex through a Yandex Cloud receiver. Events include a random persistent installation ID, a session ID, extension/VS Code versions, OS, timestamps and approved feature choices or counts. Installation IDs are pseudonymous and are not tied to your account.

Document text, file paths, usernames and exception messages/stacks are not included. The receiving infrastructure can log source IP addresses. Set VS Code telemetry.telemetryLevel to off to disable collection; error permits only classified errors. Disabling collection clears queued events and cancels pending requests. Builds without a configured endpoint send nothing.

Features

• WYSIWYG Markdown Editor — visual editing with toolbar for Diplodoc-specific blocks (notes, cuts, tabs, includes, page-constructor, HTML blocks, Mermaid diagrams)
• TOC Editor — dedicated visual editor for toc.yaml files
• YAML Validation — JSON Schema-based validation for toc.yaml, .yfm, .yfmlint, presets.yaml, redirects.yaml, theme.yaml, and page-constructor files
• Markdown Linting — real-time diagnostics via @diplodoc/yfmlint with full plugin support
• Autocompletion & Hover — YAML property completion with schema documentation
• Link Navigation — Ctrl+Click on file paths and URLs in YAML and Markdown files to open them; links with #anchor fragments navigate to the exact line of the anchor
• Anchor Completion — when typing # in a Markdown link or {% include %}, suggests correct YFM anchors from the target file: headings with explicit {#id} show only the id (not the full slug), inline {#id} anchors are included in links but excluded from includes
• Anchor Validation — warns (yellow underline) when a #anchor in a Markdown link points to a heading or {#id} that does not exist in the target file; works for cross-file links, same-file #anchor links, and links inside YAML block scalars; skips fenced code blocks; runs on open, save, and change (400 ms debounce)
• Orphan Detection — highlights .md and page-constructor .yaml files not connected to any toc.yaml in the Explorer with a ? badge; offers to remove from toc or add redirect when files are deleted; shows Code Actions on orphan files to open or add to the nearest/root toc.yaml
• Markdown Link Updates — when renaming or deleting a .md file, finds and updates all markdown links ([text](https://github.com/diplodoc-platform/vsc/blob/HEAD/path.md)) across the project, not just toc.yaml references
• Preset Variables — hover over {{variable}} to see values across all presets; Ctrl+Click to navigate to definition in presets.yaml; autocompletion inside {{ }}
• Liquid Syntax — syntax highlighting for {{ }} output tags and {% %} control tags in Markdown; paired tag highlighting for {% if %} / {% elsif %} / {% else %} / {% endif %} and {% for %} / {% endfor %}; hover and navigation for variables inside control tags
• Color Support — inline color swatches and the native color picker for color values in YAML (theme.yaml, etc.) and for {color}(text) colorify markup in Markdown; the WYSIWYG editor renders {color}(text) in any CSS color (named, hex, rgb(), hsl()); values that aren't a valid color are flagged with a warning (yellow underline) in both YAML and Markdown
• Sidebar — file browser with search, quick navigation, and project initialization
• Syntax Highlighting — YAML highlighting inside ::: page-constructor blocks in Markdown; Liquid syntax highlighting in Markdown

Requirements

VS Code 1.110+

Installation

Install from the VS Code Marketplace or via command line:

code --install-extension diplodoc.diplodoc-vsc-extension

Usage

The extension activates automatically when you open a Markdown or YAML file.

WYSIWYG Editor

Open the visual Markdown editor:

• Click the Diplodoc icon in the editor title bar
• Or run Open Diplodoc Markdown Editor from the Command Palette

The editor supports two modes: WYSIWYG and Markup. Set the default mode in settings:

{
  "diplodoc.editorMode": "wysiwyg"
}

Settings

Keyboard Shortcuts

Validation

The extension validates the following file types against Diplodoc JSON Schemas:

Markdown files are linted with @diplodoc/yfmlint. Configure lint rules via .yfmlint at your project root:

default: true
MD013: false
YFM003: error
log-levels:
  MD001: disabled

Page Constructor

YAML files with a top-level blocks: key can be edited in the WYSIWYG editor. The extension automatically detects these files and enables the visual editor button.

Sidebar

The Diplodoc sidebar in the activity bar shows all .md, toc.yaml, and page-constructor files in your workspace. Use it to:

• Browse and search project files
• Open files in the visual editor
• Initialize a new Diplodoc project (yfm init)

Contributing

See CONTRIBUTING.md for development setup, architecture overview, testing, and contribution guidelines.

License

MIT