VS Code

This page walks you through basic operations in the VS Code editor.

VS Code is not a hard requirement

The other instructions in this documentation does not strictly require VS Code to run. If you wish, you can follow everything in any editor or develop environment you prefer. Nevertheless, VS Code provides the most convinient option that with decent usability and uniform environments for collaborators.

Most of the operations in VS Code are accessible through the "Command Palette", which you can access by pressing F1 or Ctrl+Shift+P. You can search through the available commands, and alongside the commands you see shortcuts to them. A similar command is Ctrl+P (search files), that gives quick access to files (instead of finding them in the explorer to the left).

Practice

Open a Command Palette and type color theme (this should bring you to Preferences: Color Theme), chose a color theme that fits your taste.

Find the "Tasks: Run Task" command, and run the mkdocs serve task. It should start a process the builds the documentation on-the-fly. You can also open the source file of this page named as vscode.md and see how your changes are reflected in the built site.

Accessing the terminal

To access the terminal, you can use the shortcut Ctrl+`. What you bring up is the so-called "Panel" in VS Code. There contains information about running processes, debug and build information, press the shortcut again to hide the Panel.

Practice

Open and hide the panel several times. Also try creating new terminals by Ctrl+Shift+`.

Find the PORTS tab in the panel. You should recognize the port openned by mkdocs, hovering on the local address to chose how the live documentation page is displayed.

Extensions

In the (left) sidebar, you find the list of extensions installed in VS Code. In this repo, a few extensions are recommended (and should be installed by default), including checkers for typos and Markdown syntax. And a shortcut to wrap long lines with Ctrl+q. A variety of extensions are available to VS Code, some of which will be automatically recommended.

Practice

Search for the extension "GitLens" and install it to your VS Code. The extension provides a few useful interfaces to work with git, which will be demonstrated in the other instructions.

Settings

For more settings of VS Code, you can open the Settings (use the command palette). Since the VS Code is supposed to work different projects and different environments, the same setting can be set as a user (anything you open with VS Code), machine-wise or project-wise. This will come handy if you decide to use VS Code for different projects.

Think

  1. We have set up markdownlint to ignore certain rules; can you find what is set (hint: search for "markdownlint.config")?
  2. What would you do if you want to change this setting for some other project?
  3. What if you want to change some config for only yourself (not your collaborators)?

Arranging the layout

The window layout within VS Code can be easily adjusted to your need, the file views split by dragging file tabs, and the same applies to panel tabs and extensions. Before proceeding, adjust the windows to a comfortable layout.

Now, you are well-prepared to edit this document in VS Code. Move on to the next page and see how you can format the documentation using a simple language based on plain text (Markdown).

« Previous
Next »
Built with mkdocs and the flux theme.