Merge remote-tracking branch 'upstream/master'

.editorconfig

@@ -0,0 +1,5 @@
+root = true
+
+[*]
+end_of_line = lf
+trim_trailing_whitespace = true

CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Visual Studio Code Documentation
+
+You've found the GitHub repository that houses the source for the VS Code docs at <https://code.visualstudio.com/docs>.
+
+## Contribute to VS Code documentation
+
+Thank you for your interest in VS Code documentation!
+
+* [Contributing](#contributing)
+* [Documentation intent](#documentation-intent)
+* [Repository organization](#repository-organization)
+* [Branches](#branches)
+* [Authoring Tools](#authoring-tools)
+* [How to use Markdown to format your topic](#how-to-use-markdown-to-format-your-topic)
+* [Topic Metadata](#topic-metadata)
+* [Formatting](#formatting)
+
+>**Note**: Before submitting a pull request, especially for rendering or link issues, please review the content on the official VS Code website, [code.visualstudio.com](https://code.visualstudio.com). The element in question may render correctly after processing by the website build.
+
+## Contributing
+
+To contribute to [VS Code documentation](https://code.visualstudio.com/docs), you need to fork this repository and submit a pull request for the Markdown and/or image changes that you're proposing.
+
+* [How to fork a repository](https://help.github.com/articles/fork-a-repo)
+* [How to make a pull request](https://help.github.com/articles/creating-a-pull-request/)
+* [Changing a commit message](https://help.github.com/articles/changing-a-commit-message/)
+* [How to squash commits](https://help.github.com/articles/about-pull-request-merges/)
+
+## Documentation intent
+
+The goal of the VS Code documentation is to educate users on VS Code features and how VS Code can be used to enhance their development experience with different programming languages and runtimes.
+
+The documentation is not intended to provide:
+
+* An introduction to coding or software development
+* Tutorials on technologies independent from VS Code
+* Promotion of third-party tools, plug-ins or services
+* Excessive detail or advanced walkthroughs
+
+The documentation should target developers learning to use VS Code or searching for quick answers to commonly asked questions. Other forums such as blog posts can provide more detailed content elaborating on specific scenarios.
+
+## Repository organization
+
+The content in this repository follows the organization of documentation at <https://code.visualstudio.com/docs>.
+
+This repository contains the following folders:
+
+* \setup
+* \introvideos
+* \getstarted
+* \editor
+* \languages
+* \extensions
+* \extensionAPI
+* \other
+* \supporting
+
+Within these folders you'll find the Markdown files used for the content. Each of these folders also contains an \images folder that references the images (such as screenshots) used in the topics.
+
+### Branches
+
+We recommend that you create local working branches that target a specific scope of change (and then submit a pull request when your changes are ready). Each branch should be limited to a single concept/topic, both to streamline work flow, and to reduce the possibility of merge conflicts. The following efforts are of the appropriate scope for a new branch:
+
+* A new topic (and associated images).
+* Spelling and grammar edits on a topic.
+* Applying a single formatting change across a large set of topics.
+
+## Authoring tools
+
+[Visual Studio Code](https://code.visualstudio.com) is a great editor for Markdown!
+
+In fact, VS Code and its core documentation are written using VS Code.
+
+## How to use Markdown to format your topic
+
+The topics in this repository use Markdown. Here is a good overview of [Markdown basics](https://help.github.com/articles/markdown-basics/).
+
+## Topic Metadata
+
+Topic metadata enables certain functionalities for the topics such as table of contents order, topic descriptions, and online search optimization as well as aiding Microsoft in evaluating the effectiveness of the content.
+
+* **Order** - This is the order that is used in the left rail TOC, the page is left out of the TOC if this is blank
+* **Area** - General area within VS Code
+* **TOCTitle** - The title used in the left rail Table of Contents for this page
+* **PageTitle** - The title used in the HTML title for the page and in search results
+* **ContentId** - A GUID which uniquely identifies the topic to DevDiv doc reporting.
+* **DateApproved** - This is set when the page is actually published on the VS Code portal. You can ignore it.
+* **MetaDescription** - The meta description for this page which helps for search. Use sentence structure limited to 300 characters.
+* **MetaSocialImage** - Optional. Used for og:image in page header for sharing on social media. Should be 1024 x 512 .png.
+* **MetaTags** - Optional. Further tags for this page again for search.
+
+## Product name
+
+Use the full product name "Visual Studio Code" in the topic MetaDescription and the first use in a topic. You can use the shortened "VS Code" after that throughout the rest of the content. Do not use "VSCode" (no space) or "Code".
+
+### Metadata for /api docs
+
+**For Writer**:
+
+* **MetaDescription** - The meta description for this page which helps for search
+
+**For Doc Maintainer**:
+
+* **DateApproved** - This is set when the page is actually published on the VS Code portal.
+
+## Formatting
+
+### Headings & Right Nav
+
+H2 subheadings `##` end up in the right hand jump list for the document (this happens in our compile script). It's a good idea to include h2 subheadings to help users get an overview of the doc and quickly navigate to the major topics.
+
+### Text formatting
+
+Use bold for VS Code commands and UI elements.
+
+ **Extensions: Install Extension**
+ **Debug Console**
+
+Limit the use of bold for emphasis unless it is crucial to get the user's attention. Avoid the use of italics for emphasis since italics doesn't render well on the code.visualstudio.com site.
+
+Use inline code formatting (backticks) for settings, filename and JSON attributes.
+
+ `files.exclude`
+ `tasks.json`
+ `preLaunchTask`
+
+Use '>' to show menu sequence.
+
+ **File** > **Preferences** > **Settings**
+ **View** > **Command Palette**
+
+### Links
+
+For links within our own documentation, use a site relative link like `/docs/editor/codebasics.md`.
+
+>For example: `[Why VS Code](/docs/editor/whyvscode.md)` - links to the **Why Visual Studio Code** page
+
+>**Correction:** For this repo to ease content development you should add the .md suffix. We will parse these out for the website deployment.
+
+### Bookmarks
+
+To provide links to h2 subheadings (Markdown ##), the format is `[Link Text](page.md#subheading-title)`.
+
+Note the subheading title is lowercase and subheading title words are separated by '-' hyphens.
+
+>For example: `[Keyboard Shortcuts](/docs/editor/codebasics.md#keyboard-shortcuts)` - links to https://code.visualstudio.com/docs/editor/codebasics#_keyboard-shortcuts.
+
+### Images
+
+Images are important to bring the product to life - even if people can't try the product, these really help them to see what they are missing.
+
+For images you're adding to the repo, store them in the `images` subfolder of the TOC section, for example: `editor\images\debugging`.
+
+When you link to an image, the path and filename are case-sensitive. The convention is for image filenames to be all lowercase.
+
+>For example: `![Debug Breakpoints](images/debugging/breakpoints.png)`
+
+### Key bindings
+
+The VS Code portal is able to show the correct key bindings depending on the reader's operating system (macOS, Windows or Linux).
+
+To enable this for keyboard shortcuts, use the format `kb(workbench.action.files.openFile)` where the command name is included in parentheses.
+
+>For a list of key bindings and the relevant `Command Ids` review the [key bindings document](https://code.visualstudio.com/docs/getstarted/keybindings).
+
+If you are listing out multiple key bindings, you can use a table.
+
+>Shortcut|Key Strokes
+>--------|-----------
+>Cut|`kb(editor.action.clipboardCutAction)`
+>Copy|`kb(editor.action.clipboardCopyAction)`
+>Paste|`kb(editor.action.clipboardPasteAction)`
+
+### Source Code
+
+For source code we use the fenced code block notation ```` ``` ````.
+
+>**Note:** You can add an optional language identifier to enable syntax highlighting in your fenced code block. E.g. ```` ```json ```` or ```` ```javascript ````. [Read more →](https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting)
+
+Some JavaScript code...
+
+```javascript
+function fancyAlert(arg) {
+ if (arg) {
+ $.facebox({ div: foo });
+ }
+}
+```

LICENSE.md

@@ -1,11 +1,6 @@
-Copyright (c) Microsoft Corporation. All rights reserved. Distributed under the
-following terms:
+Copyright (c) Microsoft Corporation. All rights reserved. Distributed under the following terms:
 
-1. Documentation is licensed under the
- [Creative Commons Attribution 3.0 United States License](https://creativecommons.org/licenses/by/3.0/us/legalcode).
- Code is licensed under the
- [MIT License](https://opensource.org/licenses/MIT).
+1. Documentation is licensed under the [Creative Commons Attribution 3.0 United States License](https://creativecommons.org/licenses/by/3.0/us/legalcode). Code is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+2. This license does not grant you rights to use any trademarks or logos of Microsoft. For Microsoft’s general trademark guidelines, go to https://go.microsoft.com/fwlink/?LinkID=254653.
 
-2. This license does not grant you rights to use any trademarks or logos of
- Microsoft. For Microsoft’s general trademark guidelines, go to
- https://go.microsoft.com/fwlink/?LinkID=254653.

README.md

@@ -4,18 +4,13 @@
 
 # Visual Studio Code Documentation
 
-You've found the Visual Studio Code documentation GitHub repository, which
-contains the content for the
-[Visual Studio Code documentation](https://code.visualstudio.com/docs).
+You've found the Visual Studio Code documentation GitHub repository, which contains the content for the [Visual Studio Code documentation](https://code.visualstudio.com/docs).
 
-Topics submitted here will be published to the
-[Visual Studio Code](https://code.visualstudio.com) portal.
+Topics submitted here will be published to the [Visual Studio Code](https://code.visualstudio.com) portal.
 
-If you are looking for the VS Code product GitHub repository, you can find it
-[here](https://github.com/Microsoft/vscode).
+If you are looking for the VS Code product GitHub repository, you can find it [here](https://github.com/Microsoft/vscode).
 
 ## Index
-
 1. [About Visual Studio Code](#visual-studio-code)
 2. [Contributing to the documentation](#contributing-to-the-documentation)
 3. [Feedback](#feedback)
@@ -25,65 +20,47 @@ If you are looking for the VS Code product GitHub repository, you can find it
 
 ## Visual Studio Code
 
-[VS Code](https://code.visualstudio.com/) is a lightweight source code editor
-and powerful development environment for building and debugging modern web and
-cloud applications. It is free and available on your favorite platform - Linux,
-macOS, and Windows.
+[VS Code](https://code.visualstudio.com/) is a lightweight source code editor and powerful development environment for building and debugging modern web and cloud applications. It is free and available on your favorite platform - Linux, macOS, and Windows.
 
-If you landed here looking for other information about VS Code, head over to
-[our website](https://code.visualstudio.com) for additional information.
+If you landed here looking for other information about VS Code, head over to [our website](https://code.visualstudio.com) for additional information.
 
 ## Contributing to the documentation
 
-To contribute with new topics/information or make changes to existing
-documentation, see
-[contributing](https://github.com/Microsoft/vscode-docs/blob/master/CONTRIBUTING.md#contributing)
-for instructions and guidelines.
+To contribute with new topics/information or make changes to existing documentation, see [contributing](https://github.com/Microsoft/vscode-docs/blob/master/CONTRIBUTING.md#contributing) for instructions and guidelines.
 
 ## Feedback
 
-If you want to give documentation feedback, please use the feedback control
-located at the bottom of each documentation page.
+If you want to give documentation feedback, please use the feedback control located at the bottom of each documentation page.
 
 ## Documentation Issues
 
-To enter documentation bugs, please create a
-[new GitHub issue](https://github.com/Microsoft/vscode-docs/issues) (try to
-check if there isn't a topic about your issue already).
+To enter documentation bugs, please create a [new GitHub issue](https://github.com/Microsoft/vscode-docs/issues) (try to check if there isn't a topic about your issue already).
 
-If you think the issue is with the VS Code product itself, please enter issues
-[here](https://github.com/Microsoft/vscode/issues).
+If you think the issue is with the VS Code product itself, please enter issues [here](https://github.com/Microsoft/vscode/issues).
 
 ## Editing
 
-In order to edit the VS Code documentation, ensure that you have
-[Git](https://git-scm.com/downloads) installed.
+In order to edit the VS Code documentation, ensure that you have [Git](https://git-scm.com/downloads) installed.
 
 Clone a copy of the repo:
 
 ```
 git clone https://github.com/Microsoft/vscode-docs.git
 ```
 
-VS Code itself is great for reviewing and editing
-[Markdown](https://code.visualstudio.com/docs/languages/markdown) with nice
-preview support.
+VS Code itself is great for reviewing and editing [Markdown](https://code.visualstudio.com/docs/languages/markdown) with nice preview support.
 
-If you want to use VS Code, simply navigate to the `vscode-docs` directory and
-launch VS Code from there:
+If you want to use VS Code, simply navigate to the `vscode-docs` directory and launch VS Code from there:
 
 ```
 cd vscode-docs
 code .
 ```
 
-You can open any of the Markdown files and see a preview with the **Open Preview
-to the Side** button in the upper right of the editor.
+You can open any of the Markdown files and see a preview with the **Open Preview to the Side** button in the upper right of the editor.
 
 ![Markdown Preview Button](images/MDPreviewButton.png)
 
 ## Publishing
 
-Steps for how to publish documentation changes can be found
-[here](https://github.com/Microsoft/vscode-website#publishing-a-documentation-change)
-in the (private) repository of the VS Code website.
+Steps for how to publish documentation changes can be found [here](https://github.com/Microsoft/vscode-website#publishing-a-documentation-change) in the (private) repository of the VS Code website.

api/advanced-topics/extension-host.md

@@ -4,35 +4,21 @@ ContentId: 106AA11C-DB26-493A-9E3C-16F513B2AEC8
 DateApproved: 3/7/2019
 
 # Summarize the whole topic in less than 300 characters for SEO purpose
-MetaDescription:
- The Visual Studio Code Extension Host is responsible for managing extensions
- and ensuring the stability and performance of Visual Studio Code.
+MetaDescription: The Visual Studio Code Extension Host is responsible for managing extensions and ensuring the stability and performance of Visual Studio Code.
 ---
 
 # Extension Host
 
-As you learned in the [Extension Anatomy](/api/get-started/extension-anatomy)
-topic, an extension exposes the `activate` and `deactivate` methods and VS Code
-will manage its lifecycle. This topic provides more details on the **Extension
-Host** that manages all running extensions.
+As you learned in the [Extension Anatomy](/api/get-started/extension-anatomy) topic, an extension exposes the `activate` and `deactivate` methods and VS Code will manage its lifecycle. This topic provides more details on the **Extension Host** that manages all running extensions.
 
-**Extension host** is a Node.js process in VS Code responsible for loading and
-running extensions. Although you don't need to worry about the Extension Host
-when you are writing extensions, it is still useful to know what the Extension
-Host does to your extension.
+**Extension host** is a Node.js process in VS Code responsible for loading and running extensions. Although you don't need to worry about the Extension Host when you are writing extensions, it is still useful to know what the Extension Host does to your extension.
 
 ## Stability and Performance
 
-VS Code aims to deliver a stable and performant editor to end users, and
-misbehaving extensions should not impact the user experience. The Extension Host
-in VS Code prevents extensions from:
+VS Code aims to deliver a stable and performant editor to end users, and misbehaving extensions should not impact the user experience. The Extension Host in VS Code prevents extensions from:
 
--  Impacting startup performance
--  Slowing down UI operations
--  Modifying the UI
+- Impacting startup performance
+- Slowing down UI operations
+- Modifying the UI
 
-Additionally, VS Code lets extensions declare its
-[Activation Events](/api/references/activation-events) and loads them lazily.
-For example, the Markdown extension should only be loaded when a user opens a
-Markdown file. This makes sure that extensions do not consume unnecessary CPU
-and memory.
+Additionally, VS Code lets extensions declare its [Activation Events](/api/references/activation-events) and loads them lazily. For example, the Markdown extension should only be loaded when a user opens a Markdown file. This makes sure that extensions do not consume unnecessary CPU and memory.

api/advanced-topics/using-proposed-api.md

@@ -9,25 +9,14 @@ MetaDescription: Use Visual Studio Code's Proposed API
 
 # Using Proposed API
 
-At Visual Studio Code, we take Extension API compatibility seriously. We give
-our best effort to avoid breaking API changes, and extension authors could
-expect published extensions to continue to work. However, this puts great
-limitation on us: once we introduce an API, we cannot easily change it any more.
+At Visual Studio Code, we take Extension API compatibility seriously. We give our best effort to avoid breaking API changes, and extension authors could expect published extensions to continue to work. However, this puts great limitation on us: once we introduce an API, we cannot easily change it any more.
 
-Proposed API solves the problem for us. Proposed API is a set of unstable API
-that are implemented in VS Code but not exposed to the public as stable API
-does. They are **subject to change**, **only available in Insider distribution**
-and **cannot be used in published extensions**. Nevertheless, extension authors
-could test these new API in local development and provide feedback for VS Code
-team to iterate on the API. Eventually, Proposed API finds their way into the
-stable API and becomes available for general use.
+Proposed API solves the problem for us. Proposed API is a set of unstable API that are implemented in VS Code but not exposed to the public as stable API does. They are **subject to change**, **only available in Insider distribution** and **cannot be used in published extensions**. Nevertheless, extension authors could test these new API in local development and provide feedback for VS Code team to iterate on the API. Eventually, Proposed API finds their way into the stable API and becomes available for general use.
 
 ## Using Proposed API
 
 These are the steps for testing Proposed API in local extension development:
 
-- Use [Insiders](/insiders) release of VS Code.
-- Add `"enableProposedApi": true` to your `package.json`.
-- Copy the latest version of the
- [`vscode.proposed.d.ts`](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.proposed.d.ts)
- into your project.
+- Use [Insiders](/insiders) release of VS Code.
+- Add `"enableProposedApi": true` to your `package.json`.
+- Copy the latest version of the [`vscode.proposed.d.ts`](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.proposed.d.ts) into your project.