Evidence VS Code

Evidence is an open source toolkit for building data products with just SQL and markdown. Connect to your database, write SQL queries, and include charts, tables, and dynamic text - all from markdown. To get started, visit the docs.

This extension provides language support, Evidence project and dev server shortcut commands, and autocomplete for Evidence Markdown files.

Features

• Syntax highlighting for:
  • Markdown
  • SQL Query Blocks
  • Components (Svelte syntax highlighting)
  • JavaScript expressions
• Autocomplete suggestions for inserting:
  • Components (Charts, Tables, Text Components)
  • SQL Query Blocks
  • Templating (Loops, Conditionals)
• Evidence commands to:
  • Create new project
  • Start and stop dev server
  • Update to the latest version
  • View extension settings
  • Clear app data and queries cache
  • Build app for deployment to production
  • Preview Evidence markdown documents

Requirements

Evidence requires NodeJS between version 16.14 and version 20.9. You can download and install the latest long-term support (LTS) version from nodejs.org.

This extension also depends on Svelte for VS Code that provides syntax highlighting and rich intellisense for Svelte components in VS Code. Svelte for VS Code will be installed automatically when you install Evidence extension.

Installation

You can install the Evidence extension from the VS Code Marketplace, or by searching for Evidence in the VS Code Extensions tab.

Getting Started

To get started with Evidence using VS Code locally, follow these steps:

1. Open the command palette in VS Code (Cmd/Ctrl + Shift + P)

2. Search for and click New Evidence Project

3. Select an empty folder to create your Evidence project within
   
   

4. Click the Start Evidence button to install all required dependencies and start the dev server, or use the commands detailed below in the Commands section
   
   
   
   Note: The initial installation and server start can take up to 2 minutes depending on your computer. If you have issues with the startup time, you can use Codespaces (see next section).
   
   At the end of this step, your browser will automatically open to your app preview, which will appear at localhost:3000

5. We recommend putting VS Code and your browser side-by-side, like in the screenshot below. This will give you immediate development feedback on your app every time you save a markdown file.
   
   

6. Make changes to your markdown files and save the file to see the changes reflected in your app preview

7. Try the "slash commands" included with the extension by typing / - you will see a list of available viz and UI components from our library. Select a component to insert by hitting Tab or clicking on the component.
   
   Once the component code has been inserted, you can hit Tab again to move through the inputs for a component and fill them in.
   
   

Running Evidence in GitHub Codespaces

You can use the Evidence VS Code extension with GitHub Codespaces.

1. Click here to create a new project in Codespaces

2. The Evidence extension will be installed automatically

3. Click the Start Evidence button to install all required dependencies and start the dev server, or use the commands detailed below in the Commands section

4. You will get a popup saying Your application running on port 3000 is available. Click to open in browser
   
   

5. Make changes to your markdown files and save the file to see the changes reflected in your app preview

6. After making changes to your project, click the Source Control icon in the left panel and commit your changes
   
   

7. Click Publish Branch - this will prompt you to create a private or public repo for your Evidence project
   
   

8. From here, you can continue to develop your project in Codespaces, or you can choose to clone your repo locally and work from there

Commands

The Evidence extension provides a number of custom VS Code shortcut commands for Evidence projects. Most of these correspond to CLI commands which can be run from your terminal if you prefer.

You can access the VS Code shortcut commands from the command palette (Cmd/Ctrl+Shift+P) by typing Evidence in the command search box:

Deployment

You can self-host or deploy on Evidence Cloud, with a public project or behind user authentication.

Evidence projects utlize a scheduled build process, which runs the queries in your project and builds all of your pages. The output of this process is a pre-built, self-contained static web application.

This results in near instant page loads for your users and means that they are not hitting your data warehouse by interacting with their reports.

Despite this static output, you can still deliver fully interactive and exporable data products through our most recent release for Universal SQL

Sign up for Evidence Cloud here

Learn more about deployment here

Settings

Create User or Workspace Settings to change default Evidence VS Code extension Settings.

Open Evidence extension Settings in VS Code by using the Evidence: VS Code Extension Settings command, or navigating to File -> Preferences -> Settings (cmd/ctrl+,) and searching for Evidence in the Settings search box.

Available Settings

Note that after editing some settings you may need to close and reopen VS Code for the new setting to take effect.

You can request new Evidence extension settings to enhance this extension user experience in VS Code by submitting a feature request or pull request.

VS Code Settings JSON

You can also reconfigure Evidence extension settings in vscode/settings.json workspace configuration file. The .vscode/settings.json file is a JSON file that stores your VS Code Settings. It contains settings that apply globally to all workspaces open in VS Code, or to a specific workspace.

Edit your settings in ./vscode/settings.json by opening the Command Palette... with cmd/ctrl+shift+p, searching for and selecting Preferences: Open Workspace Settings (JSON) command.

Evidence Settings

All Evidence extension settings start with evidence. prefix. You can overwrite default Evidence extension settings in the open workspace directly by opening and changing /.vscode/settings.json in your project.

The following Evidence project workspace /.vscode/settings.json example sets different default Evidence dev server port, overwrites new dev server autoStart setting, and uses a modified local copy of the built-in Evidence /template project with file:// Uri to create new Evidence projects.

{
  "evidence.defaultPort": 5000,
  "evidence.autoStart": "false",
  "evidence.templateProjectUrl: "file://E:/projects/evidence.dev/template"
}

Contribute to this extension

If you would like to contribute to this VS Code extension, we welcome PRs and issues in the Github repo.

Support

If you run into any issues setting up the extension, please reach out:

• Open an issue on GitHub
• Post in our Slack community
• Email support@evidence.dev