Skip to main content

Install and configure Visual Studio Code

Author: Joseph Cayouette
Version: v1.0 (2025-10-22)

Applies to:

  • OpenSUSE Leap 15.6
  • OpenSUSE Tumbleweed
  • Ubuntu 24.04 LTS
  • WSL2 on Windows

Table of contents​

Overview​

This guide walks through installing Visual Studio Code (VS Code) and configuring it for technical documentation projects built with Asciidoctor, Antora, Make, and Jinja2 templates.
It applies to both OpenSUSE (Leap or Tumbleweed) and Ubuntu 24.04 systems.

Windows Users

If you're on Windows, consider setting up WSL2 first for the best documentation development experience. WSL2 provides a full Linux environment that works seamlessly with VS Code. See our WSL2 Setup Guide for detailed instructions.

Install Visual Studio Code​

On OpenSUSE Leap 15.6 or Tumbleweed​

  1. Import Microsoft’s GPG key:

    sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc

  2. Add the VS Code repository:

    sudo sh -c 'echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\ntype=rpm-md\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" > /etc/zypp/repos.d/vscode.repo'

  3. Refresh and install VS Code:

    sudo zypper refresh
    sudo zypper install code

On Ubuntu 24.04​

  1. Update system and install dependencies:

    sudo apt update
    sudo apt install -y wget gpg apt-transport-https software-properties-common

  2. Add Microsoft’s repository key:

    wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
    sudo install -o root -g root -m 644 packages.microsoft.gpg /usr/share/keyrings/
    rm packages.microsoft.gpg

  3. Add the VS Code repository:

    sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'

  4. Install VS Code:

    sudo apt update
    sudo apt install -y code

WSL2 on Windows​

This guide explains how to install and configure Visual Studio Code (VS Code) on Windows to work seamlessly with your WSL2 Linux distributions for development.

1. Prerequisites​

  • Ensure WSL2 is installed and a Linux distribution is set up.
  • Ensure Windows is updated to a version that supports WSL2.
  • Enable Virtual Machine Platform and Windows Subsystem for Linux features.
  • Install VS Code on Windows (not inside WSL).
  • See our WSL2 Setup Guide for complete setup instructions.

During the VS Code installation, check the "Add to PATH" option to enable the code command in WSL.

For more details, see the official VS Code WSL documentation.

2. Install VS Code and the WSL Extension​

  1. Download and install Visual Studio Code on Windows.

  2. Open VS Code and install the Remote – WSL extension (or the Remote Development pack).

  3. (Optional) In WSL, update packages and install dependencies:

    sudo apt update && sudo apt install -y wget ca-certificates

3. Opening Your WSL Folder in VS Code​

Option A — From WSL Terminal​

  1. Open your WSL terminal (Ubuntu, Debian, etc.).

  2. Navigate to your project directory:

    cd ~/projects/myapp

  3. Launch VS Code connected to WSL:

    code .

VS Code will open in Windows but connect to your WSL environment automatically. You’ll see the WSL: [Distro Name] indicator in the bottom-left corner.

Option B — From Within VS Code​

  1. Press Ctrl+Shift+P (or F1) to open the Command Palette.
  2. Type “WSL: Connect to WSL” or “Remote-WSL: New Window”.
  3. Select your Linux distribution.
  4. Open your desired folder inside WSL using File → Open Folder….

4. Developing Inside WSL​

  • The VS Code terminal runs inside WSL, not Windows.
  • Extensions that run on the Linux side will be installed in the WSL environment.
  • Use Linux-native tools, file paths, and compilers while keeping the Windows UI.

5. Tips & Best Practices​

  • Store your code inside the WSL file system (e.g., ~/projects) for better performance than using /mnt/c/.

  • Ensure consistent line endings when using Git across Windows and Linux.

  • Uninstall any Linux-native VS Code installs inside WSL if you previously installed them:

    sudo apt remove code

  • If code . doesn’t work, ensure VS Code was installed with the Add to PATH option enabled.

6. Example Workflow​

# 1. Launch WSL
wsl

# 2. Go to your project
cd ~/projects/uyuni-docs

# 3. Open in VS Code
code .

Inside VS Code:

  • Terminal runs in WSL.
  • Install dependencies (npm install, pip install, etc.).
  • Run, debug, and test applications.

To disconnect, choose Remote: Close Remote Connection.

7. References​

Once VS Code is installed, open a terminal or the command palette (Ctrl+Shift+P) and install the following extensions:

# Core documentation and language support
code --install-extension mhutchie.git-graph
code --install-extension streetsidesoftware.code-spell-checker
code --install-extension github.vscode-github-actions

# AsciiDoc tooling
code --install-extension asciidoctor.asciidoctor-vscode
code --install-extension yzhang.markdown-all-in-one

# Jinja2, Python and YAML 
code --install-extension wholroyd.jinja
code --install-extension ms-python.python
code --install-extension redhat.vscode-yaml

# Makefile and shell integration
code --install-extension ms-vscode.makefile-tools
code --install-extension foxundermoon.shell-format

# Optional: Themes and editor helpers
code --install-extension dracula-theme.theme-dracula
code --install-extension esbenp.prettier-vscode
code --install-extension ms-vscode.live-server

Configure VS Code for documentation development​

Asciidoctor and Antora​

  1. Open VS Code settings (Ctrl+,) or edit your settings.json:

    {
      "asciidoc.preview.useEditorStyle": false,
      "asciidoc.use_kroki": true,
      "asciidoc.antora.enable": true,
      "asciidoc.antora.startupProjects": ["docs"],
      "asciidoc.preview.attributes": {
        "icons": "font",
        "sectanchors": "",
        "idprefix": "",
        "idseparator": "-"
      }
    }

  2. If your project uses Antora, make sure your repository has a proper antora.yml and playbook.yml.

Jinja2 and Python​

  1. Install the Python extension and Jinja2 syntax highlighter (see above).
  2. Optionally, create a virtual environment for Python-based doc utilities: 
    python3 -m venv .venv
    source .venv/bin/activate
    pip install jinja2 pyyaml
  3. In VS Code, select your interpreter via the Python: Select Interpreter command.

Makefile Support​

  1. Install the Makefile Tools extension:

    code --install-extension ms-vscode.makefile-tools

  2. This enables IntelliSense and target detection for GNU Make builds (commonly used in doc automation).

Markdown and MDX​

For Docusaurus documentation repositories, these extensions are recommended:

code --install-extension unifiedjs.vscode-mdx
code --install-extension davidanson.vscode-markdownlint

In your workspace .vscode/settings.json, you can define:

{
  "markdownlint.config": {
    "MD013": false,
    "MD033": false
  }
}

Optional enhancements​

  • GitLens: Deep Git integration (eamodio.gitlens)
  • Path Intellisense: Auto-complete paths (christian-kohler.path-intellisense)
  • Live Preview: Quick preview for AsciiDoc and Markdown (ms-vscode.live-server)
  • YAML Support: Helpful for antora.yml files (redhat.vscode-yaml)

Testing the setup​

  1. Open a documentation repository in VS Code: 
    code ~/projects/uyuni-docs
  2. Open an .adoc file — preview it with Ctrl+Shift+V or Alt+D.
  3. Run your Antora build to confirm integration: 
    antora site.yml

Troubleshooting​

  • Missing Preview: Check that the asciidoctor.asciidoctor-vscode extension is enabled.
  • Antora errors: Verify that Node.js and Antora are installed globally.
  • Slow startup on OpenSUSE: Disable telemetry with "telemetry.telemetryLevel": "off" in settings.

With this setup, you should have a powerful environment for developing and maintaining technical documentation using Visual Studio Code on OpenSUSE or Ubuntu systems. Happy documenting!