Configure the extension

The Syside VS Code Extension reads settings from two places: a syside.toml configuration file that travels with the project, and the extension’s own syside.* settings in VS Code or a compatible editor:

A change made outside the settings page takes effect after you restart the extension: open the Command Palette (Ctrl/Cmd+Shift+P) and run Developer: Reload Window.

Settings in syside.toml

A syside.toml at the project or workspace root is the recommended way of configuring Syside: it is editor-agnostic, it is the only way to configure format options, and keeping it version tracked ensures that every team member working on the project maintains a consistent environment.

Config file discovery

If a path to the configuration file is not provided, Syside looks for syside.toml in parent directories until either one is found, or a directory with a root marker is reached. Currently, root markers include:

  • .git for a root git directory

  • sysand-lock.toml for a root Sysand directory

Up to three configuration files are discovered and merged, in order, with later files winning:

  1. Global config found at:

    • Windows: %APPDATA%\syside\syside.toml

    • Linux/macOS: $XDG_CONFIG_HOME/syside/syside.toml if exists, otherwise $HOME/.config/syside/syside.toml

    This configuration can be transferred between machines.

  2. Project-wide syside.toml, expected to be version controlled and shared between team members.

  3. Project-wide syside.user.toml in the same directory as syside.toml, or found the same way as syside.toml. This should only be used for user specific configuration options, e.g. lsp.inlay-hints, and not version controlled.

Merging is recursive for configuration objects, i.e. TOML tables, while other values, like booleans and arrays, are overwritten by the next file. An exception to this is the exclude option, which concatenates values, just like .gitignore would.

If only the global config is found, paths are resolved relative to the current working directory, otherwise they are resolved relative to the config file directory.

Edit settings on the settings page New in v1.0.0

To change the configuration files without writing TOML, open the Command Palette (Ctrl/Cmd+Shift+P) and run Syside: Open Settings (UI). The page has a tab for each file Syside reads for the workspace, in the order above: User for the global config, Project for the project-wide syside.toml wherever discovery found it, and Project (personal) for syside.user.toml. A change is saved to the tab’s file as you make it, keeping the file’s comments, and a badge on a setting shows when another file overrides it.

Syside: Open Settings (TOML) opens one of the files as text instead, creating it if it does not exist yet. A few settings can only be edited there, such as diagram style groups. A TOML extension that reads JSON schemas, such as Even Better TOML, completes and checks the options as you type.

Settings in the editor

The extension adds a smaller set of settings to the editor that hosts it, all under syside.*, such as the path to the language server executable and logging. See Settings in the editor for the full list.

Precedence

Configuration files win in discovery order, later over earlier. A setting made in the editor beats any file for the options it mirrors. On a command line, flags beat everything, and passing --config <FILE> explicitly both disables config file discovery and changes path resolution to be relative to the current working directory irrespective of the config file location.