Splitting VSCode Extension Settings into Multiple Categories

This post is over a year old, some of this information may be out of date.

I have always been adding my Visual Studio Code extension settings to the contributes.configuration object, but I was missing a way to organize the settings in multiple sections/groups. That way, the end user gets a better overview of all settings grouped by their category.

When reading the VSCode contributes.configuration schema documentation, I spotted the following: “This section can either be a single object, representing a single category of settings, or an array of objects, representing multiple categories of settings.”

As mentioned, I have always used the contributes.configuration property as a single object. However, if you want to group your settings by categories, you only need to define it as an array.

Here you can see an example of how it looks like for a single object:

1
{
2
  "contributes": {
3
    "configuration": [
4
      {
5
        "title": "Content",
6
        "properties": {
7
          "frontMatter.content.hideFm": {
8
            "type": "boolean",
9
            "markdownDescription": "%setting.frontMatter.content.hideFm.markdownDescription%"
10
          },
11
          "frontMatter.content.hideFmMessage": {
12
            "type": "string",
13
            "default": "Use the editor panel to make front matter changes",
14
            "markdownDescription": "%setting.frontMatter.content.hideFmMessage.markdownDescription%"
15
          },
16
          "frontMatter.dashboard.content.pagination": {
17
            "type": [
18
              "boolean",
19
              "number"
20
            ],
21
            "default": true,
22
            "markdownDescription": "%setting.frontMatter.dashboard.content.pagination.markdownDescription%"
23
          }
24
        }
25
      }
26
    ]
27
  }
28
}

To create multiple categories, all you need to do is change the contributes.configuration to an array, and each object you add needs to contain the title (used as the category title) and properties (used for the settings in the category) properties. When we group the settings of the above example into two categories, it looks as follows:

1
{
2
  "contributes": {
3
    "configuration": [
4
      {
5
        "title": "Content",
6
        "properties": {
7
          "frontMatter.content.hideFm": {
8
            "type": "boolean",
9
            "markdownDescription": "%setting.frontMatter.content.hideFm.markdownDescription%"
10
          },
11
          "frontMatter.content.hideFmMessage": {
12
            "type": "string",
13
            "default": "Use the editor panel to make front matter changes",
14
            "markdownDescription": "%setting.frontMatter.content.hideFmMessage.markdownDescription%"
15
          }
16
        }
17
      },
18
      {
19
        "title": "Dashboard",
20
        "properties": {
21
          "frontMatter.dashboard.content.pagination": {
22
            "type": [
23
              "boolean",
24
              "number"
25
            ],
26
            "default": true,
27
            "markdownDescription": "%setting.frontMatter.dashboard.content.pagination.markdownDescription%"
28
          }
29
        }
30
      }
31
    ]
32
  }
33
}

This results in the following outcome:

Splitting VSCode Extension Settings into Multiple Categories

Related articles

SharePoint Framework snippets extension for Visual Studio Code

SharePoint Framework Script Check extension for Visual Studio Code

#DevHack: Open custom VSCode WebView panel and focus input

Report issues or make changes on GitHub

Comments

Elio Struyf