diff --git a/content/docs/ports/visual-studio-code/customization/example-syntax-default.png b/content/docs/ports/visual-studio-code/customization/example-syntax-default.png new file mode 100644 index 00000000..9dcf5569 Binary files /dev/null and b/content/docs/ports/visual-studio-code/customization/example-syntax-default.png differ diff --git a/content/docs/ports/visual-studio-code/customization/example-syntax-overridden.png b/content/docs/ports/visual-studio-code/customization/example-syntax-overridden.png new file mode 100644 index 00000000..d0a829ad Binary files /dev/null and b/content/docs/ports/visual-studio-code/customization/example-syntax-overridden.png differ diff --git a/content/docs/ports/visual-studio-code/customization/example-workbench-ui-default.png b/content/docs/ports/visual-studio-code/customization/example-workbench-ui-default.png new file mode 100644 index 00000000..b1c33ffc Binary files /dev/null and b/content/docs/ports/visual-studio-code/customization/example-workbench-ui-default.png differ diff --git a/content/docs/ports/visual-studio-code/customization/example-workbench-ui-overridden.png b/content/docs/ports/visual-studio-code/customization/example-workbench-ui-overridden.png new file mode 100644 index 00000000..adc1bd12 Binary files /dev/null and b/content/docs/ports/visual-studio-code/customization/example-workbench-ui-overridden.png differ diff --git a/content/docs/ports/visual-studio-code/customization/index.mdx b/content/docs/ports/visual-studio-code/customization/index.mdx new file mode 100644 index 00000000..ceb80571 --- /dev/null +++ b/content/docs/ports/visual-studio-code/customization/index.mdx @@ -0,0 +1,153 @@ +import Link from "atoms/core/Link"; +import { Banner, Image, ShrinkedWidth, SpaceBox } from "atoms/core/mdx-elements"; +import { Code } from "atoms/core/html-elements"; +import { ReactComponent as PaintBrush } from "assets/images/illustrations/paint-brush.svg"; + +import WIPNotice from "../../../../shared/docs/wip-notice"; + +export const frontmatter = { + title: "Customization", + subline: + "Not in agreement with all of Nord Visual Studio Code's design decisions? No problem — simply override every theme style you like." +}; + + + + + + + + + + + + + +It is totally fine that you not agree to all design decisions and color highlighting assignments — that's the reason why themes exist. + +Even though Nord Visual Studio Code comes with sane defaults, it can still be customized down to it's core, using Visual Studio Code's builtin features, by overriding every UI (workbench) and syntax style defined by the theme. It is even possible to set new styles not defined or supported by the theme yet. + +Visual Studio Code's `workbench.colorCustomizations` and `editor.tokenColorCustomizations` user [settings][vscode-docs-settings]. Both allow to either define global styles or **only for a specific theme** like Nord Visual Studio Code while leaving other themes unaffected. + +While editing the `settings.json` file all changes will be applied on save and doesn't require to restart VS Code. + + + Please see the official VS Code documentation on{" "} + + how to customize a color theme + {" "} + for more details and customization examples. + + } +> + You can use Visual Studio Code's IntelliSense auto-completion feature while adding customizations and read the official theme color reference documentation for a list of all customizable colors. + +Also note that the settings.json file uses the JSON5 language syntax that comes with more features than the JSON specification like comments allowing to document fields and their purpose. + + + +## UI + +To override or define any workbench UI styles of Nord Visual Studio Code, e.g. lists, buttons, or the [_Activity Bar_][vscode-docs-ui-actbar], add the `workbench.colorCustomizations` object to your [settings][vscode-docs-settings] and scope the styles to only apply to _Nord_ by adding the `[Nord]` object as field. + +The following example shows how to override the colors of the activity bar and badges: + +```json5 +"workbench.colorCustomizations": { + "[Nord]": { + // Use a brighter (nord1) activity bar background color. + "activityBar.background": "#3b4252", + // Use a darker (nord9) background color for badges + // with brighter a (nord6) foreground color. + "activityBarBadge.background": "#81a1c1", + "activityBarBadge.foreground": "#eceff4" + } +} +``` + +Screenshot showing the activity bar and badges with Nord theme styles + The activity bar and badges with Nord theme styles. + + +Screenshot showing the activity bar and badges with overridden Nord theme styles + The activity bar and badges with overridden Nord theme styles. + + +## Syntax + +To override or define any code syntax styles of Nord Visual Studio Code of languages like e.g. Go or JavaScript, add the `editor.tokenColorCustomizations` object to your [settings][vscode-docs-settings] and scope the styles to only apply to _Nord_ by adding the `[Nord]` object as field. + +VS Code comes with a pre-configured set of syntax tokens, e.g. `comments` or `strings`, that apply to all languages for a easy and quick customization for every syntax while the `textMateRules` array can be used to define explicit _TextMate_ rules to fine-tune styles for every element of all languages. + + + Using TextMate grammar style rules requires advanced knowledge about the syntax! + + } + variant="warn" +> + Please read the guide about{" "} + + syntax highlighting with TextMate grammars + {" "} + for more details about the syntax and usage guides. + + +The following example shows how to override the foreground color of all comments and commas for the [Go][] syntax: + +```json5 +"editor.tokenColorCustomizations": { + "[Nord]": { + // Use a 10% brigher foreground color for all comments. + "comments": "#7b88a1", + "textMateRules": [ + { + // Also use `nord9` as comma foreground color for Go syntax. + "scope": "punctuation.other.comma.go", + "settings": { + "foreground": "#81a1c1" + } + } + ] + } +} +``` + +Screenshot showing comments and Go syntax with Nord theme styles + Comments and Go syntax with Nord theme styles. + + +Screenshot showing comments and Go syntax with overridden Nord theme styles + Comments and Go syntax with overridden Nord theme styles. + + + + +[go]: https://golang.org +[vscode-docs-colortheme-custom]: https://code.visualstudio.com/docs/getstarted/themes#_customizing-a-color-theme +[vscode-docs-colortheme]: https://code.visualstudio.com/docs/getstarted/themes +[vscode-docs-settings]: https://code.visualstudio.com/docs/getstarted/settings +[vscode-docs-ui-actbar]: https://code.visualstudio.com/docs/getstarted/userinterface#_activity-bar diff --git a/content/docs/ports/visual-studio-code/development/github-clone.png b/content/docs/ports/visual-studio-code/development/github-clone.png new file mode 100644 index 00000000..a603447a Binary files /dev/null and b/content/docs/ports/visual-studio-code/development/github-clone.png differ diff --git a/content/docs/ports/visual-studio-code/development/index.mdx b/content/docs/ports/visual-studio-code/development/index.mdx new file mode 100644 index 00000000..7fb784a0 --- /dev/null +++ b/content/docs/ports/visual-studio-code/development/index.mdx @@ -0,0 +1,109 @@ +import Button from "atoms/core/Button"; +import Link from "atoms/core/Link"; +import { Banner, Image, ShrinkedWidth, SpaceBox } from "atoms/core/mdx-elements"; +import { ReactComponent as WindowCode } from "assets/images/illustrations/window-code.svg"; +import { ROUTE_DOCS_PORTS_VISUAL_STUDIO_CODE_INSTALLATION } from "config/routes/mappings"; + +import WIPNotice from "../../../../shared/docs/wip-notice"; + +export const frontmatter = { + title: "Extension Development", + subline: "Learn how to customize the theme to fit your needs, preview changes and package the extension." +}; + + + + + + + + + + + + + +This page documents how to develop the theme extension — from requirements to VSIX packaging and the development workflow steps. + +# Requirements + +Download and install Visual Studio Code, or [Visual Studio Code Insiders][vscode-insiders] to update to the latest development state each day, with a minimal version of [1.12.0 or higher][vscode-docs-rl-1.12.0]. + +# Setup + + + Uninstall all currently installed versions of the Nord extension! + + } + variant="warn" +> + Otherwise the installed and versioned extension will collide with the development extension that'll be configured in + this guide. + + +## Download + +Clone the [_Nord Visual Studio Code_ repository from GitHub][gh-repo] to your [local extension directory][vscode-docs-extdir] where name of _Nord_'s extension directory must follow VS Code's extension naming scheme of `.-`. + +This results in the following directory name for the _Nord_ extension: `arcticicestudio.nord-visual-studio-code-0.0.0`. Note that **you can specify any version number you like**, but using `0.0.0` indicates that this is a special version for development purposes. + +```sh +git clone https://github.com/arcticicestudio/nord-visual-studio-code.git arcticicestudio.nord-visual-studio-code-0.0.0 +``` + +To get the project without [Git][] download the project as `.zip` archive file from the GitHub repository or click on the download button below. Afterwards extract the archive to your local extension directory following the directory naming scheme like described above. + + + +Screenshot showing the GitHub repository web UI to download the project repository + Download the project repository from GitHub + + +Both methods will use the `develop` branch to work with the latest development state. + +Open the extension by [adding the cloned/extracted repository directory to your workspace][vscode-docs-add-to-workspace] or opening the directory directly and set _Nord_ as active color theme like documented in the installation & activation guide. + +# Workflow + +In contrast to the immediately applied changes when editing the [user settings][vscode-docs-settings] it requires a complete restart/reload of VS Code when editing any [JSON theme files][gh-tree-themes] provided by the extension. + +To simplify the development without requiring to restart VS Code every time to preview changes + +1. add the [modified workbench UI or syntax theme key][vscode-docs-colortheme-custom] to your user settings +2. save the file to apply the changes immediately +3. add the changes to _Nord_'s JSON theme file afterwards + +This way allows to develop and preview the theme without being slowed down by the missing _hot reload_ functionality. + +# Packaging + +Visual Studio Code extensions are [packaged using the custom and installable VSIX format][vscode-docs-ext-vsixpack]. +To package, publish and manage extensions, VS Code uses the official CLI tool [`vsce`][vscode-docs-ext-vsixpack]. + +1. Follow the official documentations to learn how to [install and use the `vsce` CLI tool][vscode-docs-ext-vsce-install]. +2. Run `vsce package` in your terminal from within _Nord Visual Studio Code_'s repository to build the `.vsix` extension file. + +Please read the theme documentation about how to install and activate the generated VSIX file locally. + +Follow the Installation & Activation Guide for more details how to enable the theme. + + + +[gh-repo]: https://github.com/arcticicestudio/nord-visual-studio-code +[gh-tree-themes]: https://github.com/arcticicestudio/nord-visual-studio-code/blob/develop/themes +[git]: https://git-scm.com +[vscode-docs-add-to-workspace]: https://code.visualstudio.com/docs/editor/multi-root-workspaces#_adding-folders +[vscode-docs-colortheme-custom]: https://code.visualstudio.com/docs/getstarted/themes#_customizing-a-color-theme +[vscode-docs-ext-vsce-install]: https://code.visualstudio.com/api/working-with-extensions/publishing-extension#installation +[vscode-docs-ext-vsce]: https://code.visualstudio.com/api/working-with-extensions/publishing-extension#vsce +[vscode-docs-ext-vsixpack]: https://code.visualstudio.com/api/working-with-extensions/publishing-extension#packaging-extensions +[vscode-docs-extdir]: https://code.visualstudio.com/api/working-with-extensions/publishing-extension#your-extension-folder +[vscode-docs-rl-1.12.0]: https://code.visualstudio.com/updates/v1_12 +[vscode-docs-settings]: https://code.visualstudio.com/docs/getstarted/settings +[vscode-insiders]: https://code.visualstudio.com/insiders diff --git a/content/docs/ports/visual-studio-code/installation/index.mdx b/content/docs/ports/visual-studio-code/installation/index.mdx new file mode 100644 index 00000000..fb277135 --- /dev/null +++ b/content/docs/ports/visual-studio-code/installation/index.mdx @@ -0,0 +1,97 @@ +import Link from "atoms/core/Link"; +import { Image, ShrinkedWidth, SpaceBox } from "atoms/core/mdx-elements"; +import { Kbd } from "atoms/core/html-elements"; +import { ReactComponent as Plugin } from "assets/images/illustrations/plugin.svg"; +import { ROUTE_DOCS_PORTS_VISUAL_STUDIO_CODE_DEVELOPMENT } from "config/routes/mappings"; + +import WIPNotice from "../../../../shared/docs/wip-notice"; + +export const frontmatter = { + title: "Installation & Activation", + subline: "Get up and running in one click with the official VS Code Extension Marketplace." +}; + + + + + + + + + + + + + +Thanks to the [official VS Code Extension Marketplace][vscode-extmarket-nord], _Nord Visual Studio Code_ can be installed with one click. + +Open the [extension marketplace][vscode-docs-extmarket] by clicking on the _Extensions_ icon in the [_Activity Bar_][vscode-docs-ui-actbar] and search for `Nord`. +Click on the Install button and restart VS Code (when asked for it) to finish the installation. + + + + The builtin extension marketplace{" "} + view installed Nord theme. + + + +The extension can also be installed by running the `ext install arcticicestudio.nord-visual-studio-code` command via the _Quick Open_ widget like also described in the header of [Nord's extension page on the marketplace site][vscode-extmarket-nord]. + +### Local Installation + +A packaged VSIX file can be installed locally to use a modified variant of the theme without uploading it to the [extension marketplace][vscode-extmarket]. + +Open the drop-down menu from the „Extension“ view in the _Activity Bar_ and select „Install from VSIX…“. + +Screenshot showing the menu to install VSIX extensions locally + Local VSIX installation from the extension context menu. + + +The VSIX file picker can also be opened by running the „“ command from the _Command Palette_. + +Screenshot showing the command palette to install VSIX extensions locally + Local VSIX installation through the Command Palette. + + +Select the extension VSIX file and confirm the installation. + +Read the theme documentation on how to develop and package the theme as well as the official VS Code documentation on how to [install from a VSIX file][vscode-docs-extmarket-vsix]. + +## Activation + +To activate the _Nord_ color theme, open the [color theme picker][vscode-docs-colortheme] by clicking on the gear icon in the [_Activity Bar_][vscode-docs-ui-actbar] and select _Color Theme_ or by running the `Preferences: Color Theme` command from the [_Command Palette_][vscode-docs-ui-cmdpalette]. + + + + Opening the color theme picker through the Command Palette. + + + +Search for `Nord` and confirm the color theme change with Enter. + + + + Selecting Nord as active color theme. + + + + + +[vscode-docs-colortheme]: https://code.visualstudio.com/docs/getstarted/themes +[vscode-docs-extmarket-vsix]: https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix +[vscode-docs-extmarket]: https://code.visualstudio.com/docs/editor/extension-gallery +[vscode-docs-settings]: https://code.visualstudio.com/docs/getstarted/settings +[vscode-docs-ui-actbar]: https://code.visualstudio.com/docs/getstarted/userinterface#_activity-bar +[vscode-docs-ui-cmdpalette]: https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette +[vscode-extmarket-nord]: https://marketplace.visualstudio.com/items?itemName=arcticicestudio.nord-visual-studio-code +[vscode-extmarket]: https://marketplace.visualstudio.com diff --git a/content/docs/ports/visual-studio-code/installation/install-local-command.png b/content/docs/ports/visual-studio-code/installation/install-local-command.png new file mode 100644 index 00000000..0899f7ea Binary files /dev/null and b/content/docs/ports/visual-studio-code/installation/install-local-command.png differ diff --git a/content/docs/ports/visual-studio-code/installation/install-local-menu.png b/content/docs/ports/visual-studio-code/installation/install-local-menu.png new file mode 100644 index 00000000..09de504f Binary files /dev/null and b/content/docs/ports/visual-studio-code/installation/install-local-menu.png differ diff --git a/content/docs/ports/visual-studio-code/installation/ui-color-theme-select.png b/content/docs/ports/visual-studio-code/installation/ui-color-theme-select.png new file mode 100644 index 00000000..ac272ef9 Binary files /dev/null and b/content/docs/ports/visual-studio-code/installation/ui-color-theme-select.png differ diff --git a/content/docs/ports/visual-studio-code/installation/ui-command-palette-color-theme.png b/content/docs/ports/visual-studio-code/installation/ui-command-palette-color-theme.png new file mode 100644 index 00000000..5067fbdf Binary files /dev/null and b/content/docs/ports/visual-studio-code/installation/ui-command-palette-color-theme.png differ diff --git a/content/docs/ports/visual-studio-code/installation/ui-extension-marketplace.png b/content/docs/ports/visual-studio-code/installation/ui-extension-marketplace.png new file mode 100644 index 00000000..aac7b5b5 Binary files /dev/null and b/content/docs/ports/visual-studio-code/installation/ui-extension-marketplace.png differ diff --git a/content/shared/docs/wip-notice.mdx b/content/shared/docs/wip-notice.mdx index f2d02b16..dd30563a 100644 --- a/content/shared/docs/wip-notice.mdx +++ b/content/shared/docs/wip-notice.mdx @@ -1 +1 @@ -> This is a _living document_ which means it is **work in progress**, not completed yet and **can change at any time** while the project is still in development! +> This is a _living document_ which means it is **work in progress**, not completed yet and **can change at any time** while the project is still in [development major version _zero_](https://semver.org/#spec-item-4) `0.y.z`!