Writer: @mjbvz
Reviewer: @alexandrudima

Work should happen on: https://github.com/Microsoft/vscode-docs/blob/ext-docs/api/language-extensions/syntax-highlight-guide.md

A sample should be included in https://github.com/Microsoft/vscode-extension-samples. Follow Snippets Sample and Language Configuration Sample's setup, get rid of anything unnecessary.

The guide's positioning in the whole API docs:

It's one of the options mentioned in https://vscode-ext-docs.azurewebsites.net/api/extension-capabilities/theming. The Extension Capabilities will explain what is a color theme. This topic covers how to develop it.

The guide should cover:

• Explain what is TextMate grammar
• Explain how grammar relates to Syntax Highlighting
• Point to https://vscode-ext-docs.azurewebsites.net/api/references/contribution-points#contributes.grammars
• Explain the process of creating, developing, debugging, testing TextMate grammars
• Explain Scope Inspector
• Explain workbench.colorCustomizations and editor.tokenColorCustomizations

Nice to have

• 💪 Explain embedded grammars

References

Take content from these places:

• https://code.visualstudio.com/docs/extensions/themes-snippets-colorizers
• https://github.com/Microsoft/vscode-distro/wiki/Language-Extensions-Caretaking#debugging-a-grammar-performance-issue
• https://vscode-ext-docs.azurewebsites.net/api/extension-capabilities/theming