Elastic Docs extension for Visual Studio Code

An extension for Visual Studio Code and compatible IDEs that provides autocompletion for Elastic Docs' Markdown, as well as other features for authoring Elastic Docs authoring.

Features

Autocompletion

• Directive autocompletion: Autocompletes standard and inline directives.
• Frontmatter autocompletion: Autocompletes frontmatter fields.
• Settings autocomplete: Enter : inside a directive to view suggested settings.
• Inline role completion: Use {icon}, {kbd}, {applies_to}, and {subs} with autocompletion.
• Substitution autocompletion: Type {{ to see available substitution variables from docset.yml files and document frontmatter.
• Mutation operator completion: Type | after a substitution variable to see available mutation operators for text and version transformations.

Validation and diagnostics

• Frontmatter validation: Validates frontmatter fields against schema.
• Directive syntax validation: Real-time validation with red underlines and hover cards for errors.
• Applies-to validation: Validates applies_to syntax in frontmatter, inline roles, and section-level directives, including version format, range overlaps, and semantic rules.
• Substitution validation: Warns when literal values should be replaced with substitution variables.

Enhanced user experience

• Substitution tooltips: Hover over existing {{variable}} to see their full values and mutation transformations.
• Mutation preview: See step-by-step transformation results when hovering over variables with mutations.
• Enhanced completion tooltips: Get full variable values when selecting from autocompletion.
• Syntax highlighting: Enhanced syntax highlighting for directives, parameters, roles, substitution variables, and mutation operators that works alongside standard Markdown highlighting.
• Built-in versions: Automatically fetches and caches version substitutions from the docs-builder repository, available as {{version.*}} variables with autocompletion support.
• Vale style guide updates: Automatically checks for updates to the Elastic Vale style guide and notifies you when a new version is available.

Inline roles

The extension provides autocompletion for several inline roles:

Icon roles

Use {icon} to insert icons from Elastic's design system. Type {icon} followed by a backtick to see available icons.

Keyboard shortcuts

Use {kbd} to format keyboard shortcuts. Type {kbd} followed by a backtick to see common keys and combinations.

Applies-to roles

Use {applies_to} to specify product or deployment applicability. Type {applies_to} followed by a backtick to see available product keys and lifecycle states.

Version syntax options:

{applies_to}`stack: ga 9.1`      # 9.1+ (implicit, greater than or equal)
{applies_to}`stack: ga 9.1+`     # 9.1+ (explicit)
{applies_to}`stack: preview 9.0-9.2`  # Version range (9.0 through 9.2)
{applies_to}`stack: beta =9.1`   # Exact version only

Multiple lifecycle entries:

{applies_to}`stack: preview 9.0-9.1, ga 9.2+`
{applies_to}`elasticsearch: preview 9.0-9.1, ga 9.2-9.5, deprecated 9.6+`

Validation rules:

• Version ranges must not overlap within the same key.
• Only one unbound value (with +) is allowed per key.
• The extension provides hints for implicit version syntax and suggests explicit + or =.

Subs roles

Use {subs} for inline code that contains substitution variables. Type {subs} followed by a backtick, then use {{variable}} syntax with full autocompletion and mutation support.

Example: {subs}wget elasticsearch-{{version}}.tar.gz``

Supported directives

Admonitions

• {note} - Informational notes (supports :applies_to:)
• {warning} - Important warnings (supports :applies_to:)
• {tip} - Helpful tips (supports :applies_to:)
• {important} - Critical information (supports :applies_to:)
• {admonition} - Custom callouts (supports :applies_to:)

Content organization

• {dropdown} - Collapsible content sections (supports :applies_to:)
• {tab-set} and {tab-item} - Tabbed content (supports :group: and :sync:)
• {stepper} and {step} - Step-by-step guides
• {applies-switch} and {applies-item} - Tabbed content with applies_to badges
• {applies_to} - Section-level applicability markers with version syntax support

Media and visuals

• {image} - Images with alt text and sizing options
• {carousel} - Image carousels (supports :max-height:)
• {diagram} - Various diagram types (mermaid, d2, graphviz, plantuml, etc.)
• {math} - Mathematical expressions using LaTeX syntax (supports :label: for cross-referencing)

Content inclusion

• {include} - Include content from other files
• {csv-include} - Include and render CSV files as formatted tables

Substitution variables

The extension supports autocompletion for substitution variables defined in docset.yml files and document frontmatter (sub: field). These variables can be used throughout your markdown files with the {{variable}} syntax.

Mutation operators

Transform substitution values using mutation operators with pipe syntax:

Text case mutations:

• lc - lowercase: {{product.name | lc}}
• uc - UPPERCASE: {{product.name | uc}}
• tc - Title Case: {{product.name | tc}}
• c - Capitalize: {{product.name | c}}
• kc - kebab-case: {{product.name | kc}}
• sc - snake_case: {{product.name | sc}}
• cc - camelCase: {{product.name | cc}}
• pc - PascalCase: {{product.name | pc}}
• trim - Remove extra characters: {{value | trim}}

Version mutations:

• M - Major version: {{version | M}} (9.1.5 → 9)
• M.x - Major.x: {{version | M.x}} (9.1.5 → 9.x)
• M.M - Major.Minor: {{version | M.M}} (9.1.5 → 9.1)
• M+1 - Next major: {{version | M+1}} (9.1.5 → 10)
• M.M+1 - Next minor: {{version | M.M+1}} (9.1.5 → 9.2)

Chained mutations: Combine multiple operators: {{product.name | lc | kc}}

Shorthand notation

Use .id as shorthand for product.id: {{.elasticsearch}} is equivalent to {{product.elasticsearch}}

Frontmatter substitutions

Define document-specific substitutions in the frontmatter sub: field:

---
sub:
  my-variable: "My Value"
  version: "9.1.5"
---

These merge with docset.yml substitutions and are available throughout the document.

Built-in versions from docs-builder

The extension automatically fetches version substitutions from the docs-builder repository and makes them available as {{version.*}} variables. These versions are cached locally and refreshed automatically every hour, ensuring you always have access to the latest version information.

Available version variables:

• Type {{version. to see all available version substitutions (e.g., {{version.edot_php}}, {{version.stack}}, {{version.self}})
• Versions are automatically loaded when the extension activates
• The cache is refreshed automatically every hour in the background

Manual refresh: If you need to refresh the versions cache manually:

1. Press Ctrl/Cmd+Shift+P to open the Command Palette
2. Run Elastic Docs: Refresh Versions Cache
3. The extension will fetch the latest versions from GitHub and update the cache

The versions are sourced from the versions.yml file in the docs-builder repository and include all versioning systems defined there, such as stack versions, product-specific versions, and more.

Vale style guide update notifications

If you have the Elastic Vale style guide installed locally, the extension automatically checks for updates when it activates. When a new version is available, a notification appears with two options:

• Update: Runs the appropriate install script for your operating system in the integrated terminal.
• More Info: Opens the vale-rules repository in your browser to view release notes and documentation.

Notes:

• The check only runs if Vale is installed locally (the extension looks for the VERSION file in the standard installation path).
• If Vale is not installed, no notification is shown.
• The check runs asynchronously and fails silently if the network is unavailable, so it never affects extension performance.

Manual check: If you want to manually check for Vale style guide updates:

1. Press Ctrl/Cmd+Shift+P to open the Command Palette.
2. Run Elastic Docs: Check for Vale Style Guide Updates.

Substitution validation and quick fixes

The extension automatically detects when you're using literal values that can be replaced with substitution variables. For example, if you have a substitution variable {{product.apm}} defined in your docset.yml file with the value "APM", the extension shows a warning when you type "APM" directly in your content, suggesting you use {{product.apm}} instead.

Quick fix feature: When the extension detects a literal value that should be replaced, you can:

• Click the lightbulb icon that appears
• Use the "Quick Fix..." menu (Ctrl+. or Cmd+. on macOS)
• Hover over the warning and click "Quick Fix"

The extension will automatically replace the literal text with the correct substitution variable syntax.

This helps maintain consistency across your documentation and makes it easier to update product names and other values globally.

Quick start

1. Install the extension using the steps in the Installation section below.
2. Open a Markdown file in VS Code.
3. Try the features:
   • Type ::: to see directive completions
   • Type {icon} followed by a backtick to see icon options
   • Type {{ to see substitution variables (including built-in versions from docs-builder)
   • Type {{version. to see available version substitutions
   • Type | after a variable to see mutation operators
   • Use .elasticsearch shorthand for product.elasticsearch
   • Add sub: field in frontmatter for document-specific variables
   • Add frontmatter fields and see autocompletion
   • Notice validation warnings for literal values that could use substitutions
   • Hover over variables with mutations to see transformation previews
   • Use the Command Palette to manually refresh versions cache if needed
   • If you have Vale installed, watch for update notifications when new style guide versions are released

Installation

From the Visual Studio Marketplace

1. Open the Visual Studio Marketplace.
2. Search for "Elastic Docs Utilities" or go here.
3. Select "Install".

From the releases page

1. Download the latest .vsix file from the Releases page.
2. Start VSCode.
3. Press Ctrl/Cmd+Shift+P to open Command Palette.
4. Run Extensions: Install from VSIX....
5. Select the downloaded .vsix file.

Development

For detailed development, testing, and deployment instructions, refer to the Deployment Guide.

License

Refer to LICENSE.txt for details.