Docs-YAML Support for Visual Studio Code

Provides Docs-YAML support via yaml-language-server.

Note: This extension has been republished as Microsoft docs-yaml, and is now part of the Docs Authoring Pack. Please install the new version and uninstall the Gizmos version for ongoing updates and support.

Schemas supported to validate

There are two categories of files that we run schema validation against:

1. For YAMLMime-based YAML file, we use the the YAMLMime to match the schema which we will use to do validation according to our config.
   Those schemas are hold on this repository, Once schema files get updated, the extension will automatically pick up the latest version after a small latency (around 10min). There is no need to reopen or reload the extension.
   But if a new schema is added to this repository, to use it, we need to update this config and release extension with new version

2. For toc file, there is no YAMLMime in the beginning of file, we use the filename to match the schema, and it is case-sensitive, toc.yml and TOC.yml will both be applied schema validation(but toc.yaml will not).
   The schema used for toc YAML file is now built in the extension, and we are going to move it to schema repository in the future.

Features

New features:

• The code intellisense is more intelligent now, extension can provide the intellisense according to the schema structure but not just text mapping.(v0.1.8 and later)
• Extension can generate input template for object(including required propertied and optional properties with default value).(v0.1.8 and later)
• You can type a - to trigger the intellisense for generating a new array item.(v0.1.8 and later)

1. YAML validation

• Apply schema validation according to the YAMLMime
• Detects errors such as:
  • Invalid property value type
  • Out of enum scope
  • Required property is missing
  • Unexpected property

2. Auto completion

• Generate input template for whole YAML file

For now, the VSCode don't support auto-completion on a comment, so do not type # to get intellisense, just type YamlMime or YAMLMime type.

• Generate input template for an object(if provided by schema)

Including required properties and optional properties with default value

• Support properties intellisense(if provided by schema)
• Enumerated property value recommendation(if provided by schema)

Intellisense is automatically triggered by what you have typed, but you can also hit Ctrl + Space to get what you can type.

3. Hover support

• Hovering over a property shows description if provided by schema

Extra Knowledge

YAMLMime

A YAML syntax to identify the mime type of this YAML document, which will decide the applied schema type e.g.

### YamlMime:Module
....

• YAMLMime should be the first line
• There are should be a space between triple # and case-sensitive YamlMime
• There are should not be extra space between YamlMime, Mime-type and :

Developer Support

Developing the client side

1. Install prerequisites:
   • latest Visual Studio Code
   • Node.js v6.0.0 or higher
2. Fork this repository.
3. Build this project.

   # clone your forked repository
   $ git clone https://github.com/{your-github-name}/docs-yaml
   $ cd docs-yaml
   # install npm dependencies
   $ npm install
   # compile
   $ npm run compile
   # open the project in vscode
   $ code .

4. Make changes as necessary and the run the code using F5. Refer to VS Code documentation on how to run and debug the extension.
5. Create a pull-request to GitHub repository and we will review, merge it and publish new version extension regularly.

Contributing to schemas and snippets

Coming soon.

All contributions are welcome!