diff --git a/docs/Code-Lens.md b/docs/Code-Lens.md
new file mode 100644
index 00000000..00744513
--- /dev/null
+++ b/docs/Code-Lens.md
@@ -0,0 +1,56 @@
+
+## Code Lens
+
+### DTD features
+
+Code lens is provided in `.dtd` files to show where elements defined in the DTD are referenced.
+For instance, in the following code:
+
+```xml
+
+
+
+
+
+```
+
+There will be a code lens entry after the first line that points from the
+definition of the element `to` to where it is used in the definition of the
+element `letter`.
+
+Here is a demonstration of the above Code Lens:
+
+
+
+### XSD Features
+
+Code lens is also provided in `.xsd` files. It shows where top level types
+and elements are referenced. For instance, in the following code:
+
+```xml
+
+
+
+
+
+
+
+
+
+```
+
+There will be a code lens above the line where the `yell` type is defined
+that points to where it is referenced when defining the `root-element` element.
+
+Here is a demonstration of the above Code Lens:
+
+
+
+Here is a demonstration of the code lens for `xs:element`:
+
+
diff --git a/docs/Formatting.md b/docs/Formatting.md
index bd78c665..e1c40882 100644
--- a/docs/Formatting.md
+++ b/docs/Formatting.md
@@ -1,283 +1,335 @@
-## Formatting
-
-### xml.format.enabled
-
- Set to `false` to disable XML formatting. Defaults to `true`.
-
-***
-
-### xml.format.enforceQuoteStyle
-
-Enforce `preferred` quote style (set by `xml.preferences.quoteStyle`) or `ignore` quote style when formatting.
-
-For instance, when set to `preferred` with `xml.preferences.quoteStyle` set to `single`, the following document:
-
- ```xml
-
-
-
-
- ```
-
-will be formatted to:
-
- ```xml
-
-
-
-
- ```
-
-No changes to quotes will occur during formatting if `xml.format.enforceQuoteStyle` is set to `ignore`.
-
-***
-
-### xml.format.emptyElements
-
-Expand/collapse empty elements. Available values are `ignore`, `collapse` and `expand`. Defaults to `ignore`.
-An empty element is an element which is empty or which contains only white spaces.
-
-Set to `collapse` to collapse empty elements during formatting.
-
- ```xml
-
- ```
- becomes...
- ```xml
-
- ```
-
-Set to `expand` to expand empty elements during formatting.
-
- ```xml
-
- ```
- becomes...
- ```xml
-
- ```
-***
-
-### xml.format.preserveAttributeLineBreaks
-
-Preserve line breaks that appear before and after attributes. This setting is overridden if [xml.format.splitAttributes](Formatting#xmlformatsplitattributes-) is set to `true`. Default is `false`.
-
-If set to `true`, formatting does not change the following document:
-
- ```xml
-
-
-
-
- ```
-
-If set to `false`, the document above becomes:
-
- ```xml
-
-
-
-
- ```
-
-***
-
-### xml.format.preservedNewlines
-
-The number of blank lines to leave between tags during formatting.
-
-The default is 2. This means that if more than two consecutive empty lines are left in a document, then the number of blank lines will become 2.
-
- For example, this document:
- ```xml
-
-
-
-
-
-
-
-
-
-
-
-
-
- ```
-
- Will be replaced with:
- ```xml
-
-
-
-
-
-
-
-
-
-
- ```
-
-If this value is set to 0, then all blank lines will be removed during formatting.
-
- For example, this document:
- ```xml
-
-
-
-
-
-
-
- ```
-
- Will be replaced with:
- ```xml
-
-
-
-
- ```
-
-***
-
-### xml.format.splitAttributes
-
- Set to `true` to split node attributes onto multiple lines during formatting. Defaults to `false`.
- Overrides the behaviour of [xml.format.preserveAttributeLineBreaks](Formatting#xmlformatpreserveattributelinebreaks)
-
- ```xml
-
- ```
- becomes...
- ```xml
-
- ```
-
-***
-
-### xml.format.joinCDATALines
-
- Set to `true` to join lines in CDATA content during formatting. Defaults to `false`.
- ```xml
-
- ```
- becomes...
- ```xml
-
- ```
-***
-
-### xml.format.preserveEmptyContent
-
- Set to `true` to preserve empty whitespace content.
- ```xml
-
-
-
- ```
- becomes...
- ```xml
-
-
- ```
-***
-### xml.format.joinCommentLines
-
- Set to `true` to join lines in comments during formatting. Defaults to `false`.
- ```xml
-
- ```
- becomes...
- ```xml
-
- ```
-
-***
-
-### xml.format.joinContentLines
-
-Normalize the whitespace of content inside an element. Newlines and excess whitespace are removed. Default is `false`.
-
-For example, the following document doesn't change if it is set to `false`:
-
- ```xml
-
-
- Interesting text content
-
-
-
- values and 1234 numbers
-
-
- ```
-
-If it is set to `true`, the above document becomes:
-
- ```xml
-
- Interesting text content values and 1234 numbers
- ```
-
-***
-
-### xml.format.spaceBeforeEmptyCloseTag
-
- Set to `true` to insert a space before the end of self closing tags. Defaults to `true`
- ```xml
-
- ```
- becomes...
- ```xml
-
- ```
-
-***
-
-### files.insertFinalNewline
-
- Set to `true` to insert a final newline at the end of the document. Defaults to `false`
- ```xml
-
- ```
- becomes...
- ```xml
-
-
-
- ```
-
-***
-
-### files.trimFinalNewlines
-
- Set to `true` to trim final newlines at the end of the document. Defaults to `false`
- ```xml
-
-
-
-
-
- ```
- becomes...
- ```xml
-
- ```
-
-***
\ No newline at end of file
+## Formatting
+
+### xml.format.enabled
+
+ Set to `false` to disable XML formatting. Defaults to `true`.
+
+***
+
+### xml.format.enforceQuoteStyle
+
+Enforce `preferred` quote style (set by `xml.preferences.quoteStyle`) or `ignore` quote style when formatting.
+
+For instance, when set to `preferred` with `xml.preferences.quoteStyle` set to `single`, the following document:
+
+ ```xml
+
+
+
+
+ ```
+
+will be formatted to:
+
+ ```xml
+
+
+
+
+ ```
+
+No changes to quotes will occur during formatting if `xml.format.enforceQuoteStyle` is set to `ignore`.
+
+***
+
+### xml.format.emptyElements
+
+Expand/collapse empty elements. Available values are `ignore`, `collapse` and `expand`. Defaults to `ignore`.
+An empty element is an element which is empty or which contains only white spaces.
+
+Set to `collapse` to collapse empty elements during formatting.
+
+ ```xml
+
+ ```
+ becomes...
+ ```xml
+
+ ```
+
+Set to `expand` to expand empty elements during formatting.
+
+ ```xml
+
+ ```
+ becomes...
+ ```xml
+
+ ```
+***
+
+### xml.format.preserveAttributeLineBreaks
+
+Preserve line breaks that appear before and after attributes. This setting is overridden if [xml.format.splitAttributes](Formatting#xmlformatsplitattributes-) is set to `true`. Default is `false`.
+
+If set to `true`, formatting does not change the following document:
+
+ ```xml
+
+
+
+
+ ```
+
+If set to `false`, the document above becomes:
+
+ ```xml
+
+
+
+
+ ```
+
+***
+
+### xml.format.preservedNewlines
+
+The number of blank lines to leave between tags during formatting.
+
+The default is 2. This means that if more than two consecutive empty lines are left in a document, then the number of blank lines will become 2.
+
+ For example, this document:
+ ```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+ Will be replaced with:
+ ```xml
+
+
+
+
+
+
+
+
+
+
+ ```
+
+If this value is set to 0, then all blank lines will be removed during formatting.
+
+ For example, this document:
+ ```xml
+
+
+
+
+
+
+
+ ```
+
+ Will be replaced with:
+ ```xml
+
+
+
+
+ ```
+
+***
+
+### xml.format.splitAttributes
+
+ Set to `true` to split node attributes onto multiple lines during formatting. Defaults to `false`.
+ Overrides the behaviour of [xml.format.preserveAttributeLineBreaks](Formatting#xmlformatpreserveattributelinebreaks)
+
+ ```xml
+
+ ```
+ becomes...
+ ```xml
+
+ ```
+
+***
+
+### xml.format.joinCDATALines
+
+ Set to `true` to join lines in CDATA content during formatting. Defaults to `false`.
+ ```xml
+
+ ```
+ becomes...
+ ```xml
+
+ ```
+***
+
+### xml.format.preserveEmptyContent
+
+ Set to `true` to preserve empty whitespace content.
+ ```xml
+
+
+
+ ```
+ becomes...
+ ```xml
+
+
+ ```
+***
+### xml.format.joinCommentLines
+
+ Set to `true` to join lines in comments during formatting. Defaults to `false`.
+ ```xml
+
+ ```
+ becomes...
+ ```xml
+
+ ```
+
+***
+
+### xml.format.joinContentLines
+
+Normalize the whitespace of content inside an element. Newlines and excess whitespace are removed. Default is `false`.
+
+For example, the following document doesn't change if it is set to `false`:
+
+ ```xml
+
+
+ Interesting text content
+
+
+
+ values and 1234 numbers
+
+
+ ```
+
+If it is set to `true`, the above document becomes:
+
+ ```xml
+
+ Interesting text content values and 1234 numbers
+ ```
+
+***
+
+### xml.format.spaceBeforeEmptyCloseTag
+
+ Set to `true` to insert a space before the end of self closing tags. Defaults to `true`
+ ```xml
+
+ ```
+ becomes...
+ ```xml
+
+ ```
+
+***
+
+### files.insertFinalNewline
+
+ Set to `true` to insert a final newline at the end of the document. Defaults to `false`
+ ```xml
+
+ ```
+ becomes...
+ ```xml
+
+
+
+ ```
+
+***
+
+### files.trimFinalNewlines
+
+ Set to `true` to trim final newlines at the end of the document. Defaults to `false`
+ ```xml
+
+
+
+
+
+ ```
+ becomes...
+ ```xml
+
+ ```
+
+***
+### xml.format.xsiSchemaLocationSplit
+
+ Used to configure how to format the content of `xsi:schemaLocation`.
+
+ To explain the different settings, we will use this xml document as an example:
+ ```xml
+
+
+
+ ```
+ Note that it references two different external schemas. Additionally, the setting `xml.format.splitAttributes` will be set to true for the formatted examples in order to make the formatted result easier to see.
+
+ * When it is set to `none`, the formatter does not change the content of `xsi:schemaLocation`. The above file would not change after formatting.
+
+ * When it is set to `onPair`, the formatter groups the content into pairs of namespace and URI, and inserts a new line after each pair. Assuming the other formatting settings are left at their default, the above file would look like this:
+ ```xml
+
+
+
+ ```
+
+ * When it is set to `onElement`, the formatter inserts a new line after each namespace and each URI.
+ ```xml
+
+
+
+ ```
+
+***
+
diff --git a/docs/Preferences.md b/docs/Preferences.md
new file mode 100644
index 00000000..680f435e
--- /dev/null
+++ b/docs/Preferences.md
@@ -0,0 +1,146 @@
+## File Associations
+
+ Can be accessed through `xml.fileAssociations`.
+
+ Provides ability to associate a schema with a file pattern.
+
+ Example:
+ ```json
+ [
+ {
+ "systemId": "path/to/file.xsd",
+ "pattern": "file1.xml"
+ },
+ {
+ "systemId": "http://www.w3.org/2001/XMLSchema.xsd",
+ "pattern": "**/*.xsd"
+ }
+ ]
+ ```
+
+ Please see [XMLValidation#xml-file-association](XMLValidation#xml-file-association) for more information.
+
+## Server VM Arguments
+
+ Can be accessed through `xml.server.vmargs`.
+
+ Setting up proxy:
+
+ A proxy can be defined in the following way if there is a system proxy:
+
+ ```
+ -Djava.net.useSystemProxies=true -Dhttp.proxyUser= -Dhttp.proxyPassword=
+ ```
+
+ or if there is not a system proxy:
+
+ ```
+ -Dhttp.proxyHost= -Dhttp.proxyPort= -Dhttp.proxyUser=
+ -Dhttp.proxyPassword= -Dhttps.proxyHost= -Dhttps.proxyPort=
+ ```
+
+## Catalogs
+
+ Can be accessed through `xml.catalogs`.
+
+ Catalogs describe a mapping between external entity references and locally cached equivalents.
+
+ The format should include local files and look like:
+
+ ```json
+ "catalogs": [
+ "catalog.xml",
+ "catalog2.xml"
+ ]
+ ```
+## Grammar
+
+ Can be accessed through: `xml.problems.noGrammar`
+
+ When there are issues with grammar constraints like (Catalogs or Associations not properly configured)
+ you can set message severity of the message the client will receive.
+
+ Options:
+
+* ignore
+* hint **(default)**
+* info
+* warning
+* error
+
+## Server Cache Path
+
+Set custom path for cached schemas (eg: XSD).
+The path must be absolute, and works with the '~' shortcut for the home directory.
+
+eg: `~/cache/.lemminxCache`
+
+The default path is: `~/.lemminx`.
+
+## Formatting
+
+See the [Formatting page](Formatting).
+
+## Code Lens
+
+Use `xml.codeLens.enabled` in order to enable or disable code lens. Please see [Code Lens page](./CodeLens) for more information.
+
+## Documentation Type
+
+Use `xml.preferences.showSchemaDocumentationType` in order to control which documentation is presented during completion and hover for XML documents associated with XSD schemas.
+When you hover over an element in an XML document, the documentation is pulled from the `xs:documentation` and `xs:appinfo` elements. These elements are nested under the definition of the hovered element in the schema.
+
+As an example, here is a schema with documentation:
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+ Used to distinguish boots of different sizes
+ The size of the boot
+ This number is not based on metric or imperial units of measurement
+
+
+
+
+ Used to accurately display the boots color
+ The color of the boot as an RBG hexadecimal number
+
+
+
+
+
+
+
+ Contains the boots
+ Holds zero or more boots
+
+
+
+
+
+
+
+
+```
+
+The different options are:
+ * `documentation`: Show only the content of `xs:documentation` elements
+ * `appinfo`: Show only the content of `xs:appinfo` elements
+ * `all`: Show the content of `xs:appinfo` and `xs:documentation`, separated by subtitles
+ * `none`: Neither `xs:appinfo` nor `xs:documentation` are shown.
+
+Here is a demonstration of the effects of the setting on hovering. The above schema is used in the example:
+
+
diff --git a/docs/Validation.md b/docs/Validation.md
index 6202cacb..5d1d3946 100644
--- a/docs/Validation.md
+++ b/docs/Validation.md
@@ -1,296 +1,318 @@
-# XML Validation
-
-## XML Syntax Errors
-
-[vscode-xml](https://github.com/redhat-developer/vscode-xml) provides the capability to `report XML syntax errors` when the XML is not valid:
-
-
-
-For many of the errors, you can use a `Quick Fix` (code action) to help you fix the XML:
-
-
-
-## Validation with a given grammar
-
-You can `validate your XML with a grammar` (XSD, DTD). In order to do so, you must associate your XML document with a grammar. Once you have done this, you will benefit from:
-
- * XML `validation` based on the grammar.
- * XML `completion` based on the grammar.
- * XML `hover` based on the grammar in order to show the documentation.
-
-## Validation with XSD grammar
-
-In the following sections, we would like to validate the XML `foo.xml` file:
-
-```xml
-
-
-
-```
-
-with the XSD `foo.xsd` file (in the same folder as foo.xml) :
-
-```xml
-
-
-
-
-
-
-
-
-
-
-```
-
-in order to benefit from validation, completion, and hover based on the XSD:
-
-
-
-To associate your XML document with an XSD grammar, you can use several strategies:
-
- * [xsi:noNamespaceSchemaLocation](#xsinonamespaceschemalocation)
- * [xsi:schemaLocation](#xsischemalocation)
- * [xml-model with XSD](#xml-model-with-XSD) processing instruction
- * [XML catalog with XSD](#XML-catalog-with-XSD)
- * [XML file association](#XML-file-association)
-
-If you have an XML without an XSD, you can generate the XSD with a `Quick Fix` (code action):
-
-
-
-The Quick Fix will generate the XSD file and associate the XML with the XSD using the chosen strategy.
-
-### xsi:noNamespaceSchemaLocation
-
-To bind the XML file `foo.xml` with the XSD file `foo.xsd`, you can use the `xsi:noNamespaceSchemaLocation` strategy like this:
-
-```xml
-
-
-
-```
-
-### xsi:schemaLocation
-
-The `xsi:schemaLocation` strategy is used when the XSD file defines a `targetNamespace="http://foo"` in the root element of the XSD:
-
-```xml
-
-
-
-
-
-
-
-
-
-
-```
-
-You can bind the XSD like this:
-
-```xml
-
-
-
-```
-
-### xml-model with XSD
-
-To bind the XML file `foo.xml` to the XSD file `foo.xsd`, you can use [xml-model](https://www.w3.org/TR/xml-model/) processing instruction strategy like this:
-
-```xml
-
-
-
-
-```
-
-### XML catalog with XSD
-
-Using an XML catalog can be helpful when you wish to use elements from a namespace but don't want to set the real path of the XSD file for each XML document.
-
-In other words you want to write this XML file:
-
-
-```xml
-
-
-
-```
-
-and validate it with the `foo.xsd` XSD file:
-
-```xml
-
-
-
-
-
-
-
-
-
-
-```
-
-To do this, you need to write an XML catalog, and an entry for the XSD. In this example, we'll name the catalog `catalog.xml`. The catalog looks like this:
-
-```xml
-
-
-
-
-
-```
-
-You must register your `catalog.xml` in the vscode `settings.json` like this:
-
-```json
-"xml.catalogs": [
- "catalog.xml"
-]
-```
-
-You can also register the catalog using its absolute path:
-
-| Windows | MacOS | Linux |
-| ---------------------------------- | ---------------------------- | --------------------------- |
-| `C:\\Users\\path\\to\\catalog.xml` | `/Users/path/to/catalog.xml` | `/home/path/to/catalog.xml` |
-
-Please note that you can declare your catalog path with `file:///` if you need it.
-
-### XML file association
-
-You can use the XML file association strategy to bind the XML file `foo.xml` with the XSD file `foo.xsd` by adding the following into your vscode `settings.json`:
-
-```json
-"xml.fileAssociations": [
- {
- "pattern": "foo.xml",
- "systemId": "foo.xsd"
- }
-]
-```
-
-Please note that you can use wildcards in the pattern (ex: `foo*.xml`):
-
-```json
-"xml.fileAssociations": [
- {
- "pattern": "foo*.xml",
- "systemId": "foo.xsd"
- }
-]
-```
-
-In this case, all XML files that start with foo and end with .xml will be associated with the XSD (foo1.xml, foo2.xml, etc)
-
-## Validation with DTD grammar
-
-To associate your XML with a DTD grammar you can use several strategies:
-
- * [DOCTYPE](#DOCTYPE)
- * [xml-model with DTD](#xml-model-with-DTD) processing instruction
- * [XML catalog with DTD](#XML-catalog-with-DTD)
- * XML file association is not supported for DTD at the moment. Please see [issue 184](https://github.com/redhat-developer/vscode-xml/issues/184))
-
-In the following sections we would like to validate the XML `foo.xml` file:
-
-```xml
-
-
-
-```
-
-with the DTD `foo.dtd` file:
-
-```xml
-
-
-```
-
-Please note: this DTD file can be generated with the same Quick Fix which generates the XSD.
-
-### DOCTYPE
-
-To bind the XML file `foo.xml` with the DTD file `foo.dtd`, you can use the `DOCTYPE` strategy like this:
-
-```xml
-
-
-
-
-```
-
-### xml-model with DTD
-
-To bind XML file `foo.xml` with the DTD file `foo.dtd`, you can use [xml-model](https://www.w3.org/TR/xml-model/) processing instruction strategy like this:
-
-```xml
-
-
-
-
-```
-
-### XML catalog with DTD
-
-Using an XML catalog can be helpful when you wish to associate to a DTD using a PUBLIC declaration, but don't want to set the real path of the DTD file (SYSTEM).
-
-In other words you want to write this XML file:
-
-```xml
-
-
-
-
-```
-
-and validate it with this `foo.dtd` DTD file:
-
-```xml
-
-
-```
-
-The declared `XXXXXXXXXXXXXXX.dtd` in the DOCTYPE is a file which doesn't exist. The `foo.dtd` will be retrieved using the PUBLIC `-//FOO`.
-
-To do this, you need to write an XML catalog, and an entry for the DTD. In this example, we'll name the catalog `catalog.xml`. The catalog looks like this:
-
-```xml
-
-
-
-
-
-```
-
-and in vscode `settings.json` you must register your `catalog.xml` like this:
-
-```json
-"xml.catalogs": [
- "catalog.xml"
-]
-```
-
-You can also register the catalog using its absolute path:
-
-| Windows | MacOS | Linux |
-| ---------------------------------- | ---------------------------- | --------------------------- |
-| `C:\\Users\\path\\to\\catalog.xml` | `/Users/path/to/catalog.xml` | `/home/path/to/catalog.xml` |
+# XML Validation
+
+## XML Syntax Errors
+
+[vscode-xml](https://github.com/redhat-developer/vscode-xml) provides the capability to `report XML syntax errors` when the XML is not valid:
+
+
+
+For many of the errors, you can use a `Quick Fix` (code action) to help you fix the XML:
+
+
+
+## Validation with a given grammar
+
+You can `validate your XML with a grammar` (XSD, DTD). In order to do so, you must associate your XML document with a grammar. Once you have done this, you will benefit from:
+
+ * XML `validation` based on the grammar.
+ * XML `completion` based on the grammar.
+ * XML `hover` based on the grammar in order to show the documentation.
+
+## Validation with XSD grammar
+
+In the following sections, we would like to validate the XML `foo.xml` file:
+
+```xml
+
+
+
+```
+
+with the XSD `foo.xsd` file (in the same folder as foo.xml) :
+
+```xml
+
+
+
+
+
+
+
+
+
+
+```
+
+in order to benefit from validation, completion, and hover based on the XSD:
+
+
+
+To associate your XML document with an XSD grammar, you can use several strategies:
+
+ * [xsi:noNamespaceSchemaLocation](#xsinonamespaceschemalocation)
+ * [xsi:schemaLocation](#xsischemalocation)
+ * [xml-model with XSD](#xml-model-with-XSD) processing instruction
+ * [XML catalog with XSD](#XML-catalog-with-XSD)
+ * [XML file association](#XML-file-association)
+
+If you have an XML without an XSD, you can generate the XSD with a `Quick Fix` (code action):
+
+
+
+The Quick Fix will generate the XSD file and associate the XML with the XSD using the chosen strategy.
+
+### xsi:noNamespaceSchemaLocation
+
+To bind the XML file `foo.xml` with the XSD file `foo.xsd`, you can use the `xsi:noNamespaceSchemaLocation` strategy like this:
+
+```xml
+
+
+
+```
+
+### xsi:schemaLocation
+
+The `xsi:schemaLocation` strategy is used when the XSD file defines a `targetNamespace="http://foo"` in the root element of the XSD:
+
+```xml
+
+
+
+
+
+
+
+
+
+
+```
+
+You can bind the XSD like this:
+
+```xml
+
+
+
+```
+
+### xml-model with XSD
+
+To bind the XML file `foo.xml` to the XSD file `foo.xsd`, you can use [xml-model](https://www.w3.org/TR/xml-model/) processing instruction strategy like this:
+
+```xml
+
+
+
+
+```
+
+### XML catalog with XSD
+
+Using an XML catalog can be helpful when you wish to use elements from a namespace but don't want to set the real path of the XSD file for each XML document.
+
+In other words you want to write this XML file:
+
+
+```xml
+
+
+
+```
+
+and validate it with the `foo.xsd` XSD file:
+
+```xml
+
+
+
+
+
+
+
+
+
+
+```
+
+To do this, you need to write an XML catalog, and an entry for the XSD. In this example, we'll name the catalog `catalog.xml`. The catalog looks like this:
+
+```xml
+
+
+
+
+
+```
+
+You must register your `catalog.xml` in the vscode `settings.json` like this:
+
+```json
+"xml.catalogs": [
+ "catalog.xml"
+]
+```
+
+You can also register the catalog using its absolute path:
+
+| Windows | MacOS | Linux |
+| ---------------------------------- | ---------------------------- | --------------------------- |
+| `C:\\Users\\path\\to\\catalog.xml` | `/Users/path/to/catalog.xml` | `/home/path/to/catalog.xml` |
+
+Please note that you can declare your catalog path with `file:///` if you need it.
+
+### XML file association
+
+You can use the XML file association strategy to bind the XML file `foo.xml` with the XSD file `foo.xsd` by adding the following into your vscode `settings.json`:
+
+```json
+"xml.fileAssociations": [
+ {
+ "pattern": "foo.xml",
+ "systemId": "foo.xsd"
+ }
+]
+```
+
+Please note that you can use wildcards in the pattern (ex: `foo*.xml`):
+
+```json
+"xml.fileAssociations": [
+ {
+ "pattern": "foo*.xml",
+ "systemId": "foo.xsd"
+ }
+]
+```
+
+In this case, all XML files that start with foo and end with .xml will be associated with the XSD (foo1.xml, foo2.xml, etc)
+
+## Validation with DTD grammar
+
+To associate your XML with a DTD grammar you can use several strategies:
+
+ * [DOCTYPE](#DOCTYPE)
+ * [xml-model with DTD](#xml-model-with-DTD) processing instruction
+ * [XML catalog with DTD](#XML-catalog-with-DTD)
+ * XML file association is not supported for DTD at the moment. Please see [issue 184](https://github.com/redhat-developer/vscode-xml/issues/184))
+
+In the following sections we would like to validate the XML `foo.xml` file:
+
+```xml
+
+
+
+```
+
+with the DTD `foo.dtd` file:
+
+```xml
+
+
+```
+
+Please note: this DTD file can be generated with the same Quick Fix which generates the XSD.
+
+### DOCTYPE
+
+To bind the XML file `foo.xml` with the DTD file `foo.dtd`, you can use the `DOCTYPE` strategy like this:
+
+```xml
+
+
+
+
+```
+
+### xml-model with DTD
+
+To bind XML file `foo.xml` with the DTD file `foo.dtd`, you can use [xml-model](https://www.w3.org/TR/xml-model/) processing instruction strategy like this:
+
+```xml
+
+
+
+
+```
+
+### XML catalog with DTD
+
+Using an XML catalog can be helpful when you wish to associate to a DTD using a PUBLIC declaration, but don't want to set the real path of the DTD file (SYSTEM).
+
+In other words you want to write this XML file:
+
+```xml
+
+
+
+
+```
+
+and validate it with this `foo.dtd` DTD file:
+
+```xml
+
+
+```
+
+The declared `XXXXXXXXXXXXXXX.dtd` in the DOCTYPE is a file which doesn't exist. The `foo.dtd` will be retrieved using the PUBLIC `-//FOO`.
+
+To do this, you need to write an XML catalog, and an entry for the DTD. In this example, we'll name the catalog `catalog.xml`. The catalog looks like this:
+
+```xml
+
+
+
+
+
+```
+
+and in vscode `settings.json` you must register your `catalog.xml` like this:
+
+```json
+"xml.catalogs": [
+ "catalog.xml"
+]
+```
+
+You can also register the catalog using its absolute path:
+
+| Windows | MacOS | Linux |
+| ---------------------------------- | ---------------------------- | --------------------------- |
+| `C:\\Users\\path\\to\\catalog.xml` | `/Users/path/to/catalog.xml` | `/home/path/to/catalog.xml` |
+
+
+
+# Other Validation Settings
+
+## Disallow Doc Type Declarations
+
+If `xml.validation.disallowDocTypeDeclaration` is set to `true` (default is `false`), all Doc Type Declarations (DTD) will be marked as errors. The DOCTYPE is marked as an error regardless if the doctype is an internally declared or a reference to an external DTD. Standalone `.dtd` files are not marked as an error.
+
+Here are some examples of files with `xml.validation.disallowDocTypeDeclaration` set to true:
+
+
+
+
+
+## Resolve External Entities
+
+If `xml.validation.resolveExternalEntities` is set to `true` (default is `false`), then the value of [external entities](https://www.w3schools.com/xml/xml_dtd_entities.asp) are resolved for validation. This means that the file referenced in the external entity declaration will be downloaded. The default is `false` due to [the xml external entity attack](https://en.wikipedia.org/wiki/XML_external_entity_attack).
+
+Demonstration of the different behaviour:
+
+
diff --git a/docs/images/code-lens/DTDElementCodeLens.gif b/docs/images/code-lens/DTDElementCodeLens.gif
new file mode 100644
index 00000000..b49eace8
Binary files /dev/null and b/docs/images/code-lens/DTDElementCodeLens.gif differ
diff --git a/docs/images/code-lens/XSDElementCodeLens.gif b/docs/images/code-lens/XSDElementCodeLens.gif
new file mode 100644
index 00000000..f479b2a5
Binary files /dev/null and b/docs/images/code-lens/XSDElementCodeLens.gif differ
diff --git a/docs/images/code-lens/XSDTypeCodeLens.gif b/docs/images/code-lens/XSDTypeCodeLens.gif
new file mode 100644
index 00000000..079f9561
Binary files /dev/null and b/docs/images/code-lens/XSDTypeCodeLens.gif differ
diff --git a/docs/images/disallow-doctype/DoctypeError1.png b/docs/images/disallow-doctype/DoctypeError1.png
new file mode 100644
index 00000000..16a3ad77
Binary files /dev/null and b/docs/images/disallow-doctype/DoctypeError1.png differ
diff --git a/docs/images/disallow-doctype/DoctypeError2.png b/docs/images/disallow-doctype/DoctypeError2.png
new file mode 100644
index 00000000..daaf6a81
Binary files /dev/null and b/docs/images/disallow-doctype/DoctypeError2.png differ
diff --git a/docs/images/preferences/HoverDocumentationQuickDemo.gif b/docs/images/preferences/HoverDocumentationQuickDemo.gif
new file mode 100644
index 00000000..74c6cc58
Binary files /dev/null and b/docs/images/preferences/HoverDocumentationQuickDemo.gif differ
diff --git a/docs/images/validation/ExternalEntityResolvingDemonstration.gif b/docs/images/validation/ExternalEntityResolvingDemonstration.gif
new file mode 100644
index 00000000..f7e2c10c
Binary files /dev/null and b/docs/images/validation/ExternalEntityResolvingDemonstration.gif differ
diff --git a/package.json b/package.json
index e70533d3..b1dfc19b 100644
--- a/package.json
+++ b/package.json
@@ -152,7 +152,7 @@
"pattern"
]
},
- "markdownDescription": "Allows XML schemas/ DTD to be associated to file name patterns.\n\nExample:\n```json\n[{\n \"systemId\": \"path/to/file.xsd\",\n \"pattern\": \"file1.xml\"\n},\n{\n \"systemId\": \"http://www.w3.org/2001/XMLSchema.xsd\",\n \"pattern\": \"**/*.xsd\"\n}]\n```",
+ "markdownDescription": "Allows XML schemas/ DTD to be associated to file name patterns. Please refer to [the validation documentation](command:xml.open.docs?%5B%7B%22page%22%3A%22Validation%22%2C%22section%22%3A%22xml-file-association%22%7D%5D) for more information. \n\nExample:\n```json\n[{\n \"systemId\": \"path/to/file.xsd\",\n \"pattern\": \"file1.xml\"\n},\n{\n \"systemId\": \"http://www.w3.org/2001/XMLSchema.xsd\",\n \"pattern\": \"**/*.xsd\"\n}]\n```",
"scope": "window"
},
"xml.format.enabled": {
@@ -275,7 +275,7 @@
"xml.codeLens.enabled": {
"type": "boolean",
"default": false,
- "description": "Enable/disable XML CodeLens. Default is `false`."
+ "markdownDescription": "Enable/disable XML CodeLens. Default is `false`. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22Code-Lens%22%2C%22section%22%3A%22Code%20Lens%22%7D%5D) for information about CodeLens features"
},
"xml.preferences.showSchemaDocumentationType": {
"type": "string",