Virtual Include Extension for VS Code

Include content from other files with automatic updates and edit protection.

Overview

Virtual Include is a powerful VS Code extension that allows you to include content from other files directly in your code. Unlike traditional includes which require preprocessing, Virtual Include works with any language and automatically updates content when source files change.

Features

• ✅ Language Agnostic: Works with JavaScript, TypeScript, Python, Ruby, C#, Java, HTML, CSS, and more
• ✅ Live Updates: Content automatically updates when source files change
• ✅ Protected Content: Included content is protected from accidental edits
• ✅ Visual Feedback: Error indicators for missing files and status bar integration
• ✅ Multiple Languages: Adapts to each language's comment style

Installation

1. Open VS Code
2. Press Ctrl+P (or Cmd+P on Mac)
3. Type ext install artworkad.vscode-virtual-include
4. Press Enter

How to Use

Basic Usage

1. Add a virtual include directive in your code using your language's comment style
2. Reference the file you want to include
3. Save the document

The extension will automatically process the include directive and insert the content from the referenced file. The included content is protected from edits - if you want to change it, edit the source file instead!

Include Directive Format

The include directive follows this format:

[comment style] virtualInclude '[path]'

Where:

• [comment style] is the comment syntax for your language
• [path] is the path to the file you want to include (relative to the current file or absolute)

Examples

JavaScript/TypeScript:

// virtualInclude 'utils/helper.js'

Python:

# virtualInclude 'models/user.py'

HTML:

<!-- virtualInclude 'components/header.html' -->

CSS:

/* virtualInclude 'styles/variables.css' */

C/C++/Java/C#:

// virtualInclude 'common/math.h'

Ruby:

# virtualInclude 'lib/utilities.rb'

After Processing

When you save the file, the extension will process the include directive and insert the content from the referenced file. The included content will be wrapped between start and end markers:

// virtualInclude 'utils/helper.js'
// virtualIncludeStart - DO NOT EDIT CONTENT BELOW
function helperFunction() {
  return 'Hello, world!';
}
// virtualIncludeEnd - DO NOT EDIT CONTENT ABOVE

Indentation

The extension automatically preserves the indentation from the include directive line, so included content will match your code style:

function example() {
  // virtualInclude 'utils/helper.js'
  // virtualIncludeStart - DO NOT EDIT CONTENT BELOW
  function helperFunction() {
    return 'Hello, world!';
  }
  // virtualIncludeEnd - DO NOT EDIT CONTENT ABOVE
}

Error Handling

If a referenced file cannot be found, the extension will show an error indicator (red squiggly line) under the include directive. Hovering over it will show the specific error message.

User Interface

Status Bar

The extension adds a status bar item that shows the current state:

• 📎 Virtual Include: Normal state
• 🔄 Processing Includes: When the extension is processing includes
• ⚠️ Virtual Include (X issues): When there are problems with includes

You can click the status bar item to manually trigger include processing.

Notifications

When a source file changes, the extension will show a notification with options to:

• Show affected files
• Save all affected files

Settings

You can customize the extension's behavior through VS Code settings:

"virtualInclude": {
  "defaultCommentStyle": "#",
  "languageSettings": {
    "javascript": {
      "includeDirectivePattern": "\/\/\\s*virtualInclude\\s+[\"'](https://github.com/artworkad/vscode-virtual-include/blob/HEAD/.+?)[\"']",
      "startMarkerTemplate": "// virtualIncludeStart - DO NOT EDIT CONTENT BELOW",
      "endMarkerTemplate": "// virtualIncludeEnd - DO NOT EDIT CONTENT ABOVE"
    }
  }
}

Available Settings

• virtualInclude.defaultCommentStyle: Default comment style for languages without specific settings (defaults to #)
• virtualInclude.languageSettings: Override settings for specific languages with custom patterns and markers

Advanced Usage

Custom Include Patterns

You can customize the include directive pattern, start marker, and end marker for each language using the settings:

"virtualInclude.languageSettings": {
  "python": {
    "includeDirectivePattern": "#\\s*import\\s+[\"'](https://github.com/artworkad/vscode-virtual-include/blob/HEAD/.+?)[\"']",
    "startMarkerTemplate": "# BEGIN IMPORT - DO NOT EDIT",
    "endMarkerTemplate": "# END IMPORT - DO NOT EDIT"
  }
}

With these settings, Python includes would look like:

# import 'models/user.py'
# BEGIN IMPORT - DO NOT EDIT
class User:
    def __init__(self, name):
        self.name = name
# END IMPORT - DO NOT EDIT

Use Cases

Configuration Files

Include common configuration settings across multiple files:

// config.js
// virtualInclude 'common-config.js'

Code Snippets

Include common code snippets:

# api.py
# virtualInclude 'error-handling.py'

Documentation

Include documentation sections:

<!-- README.md -->
<!-- virtualInclude 'installation.md' -->

Templates

Include common HTML templates:

<!-- index.html -->
<!-- virtualInclude 'header.html' -->

Commands

The extension contributes the following commands:

• Process Virtual Includes: Manually process all virtual includes in the current file

You can access this command from:

• Right-click context menu in the editor
• Command palette (Ctrl+Shift+P or Cmd+Shift+P on Mac)
• Clicking the Virtual Include status bar item

Troubleshooting

Issue: Include is not updating when source file changes

Solution: Make sure file watchers are enabled in your environment. Some network drives may not support file watching.

Issue: Content is not being included correctly

Solution: Check that the path is correct and relative to the current file, not the workspace root.

Issue: Start/end markers are missing

Solution: Try manually saving the file to trigger include processing, or use the "Process Virtual Includes" command from the context menu.

Requirements

• VS Code ^1.98.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Publisher

Published by artworkad