diff --git a/docs/Features/XMLFeatures.md b/docs/Features/XMLFeatures.md index 2fc21848..72e41c13 100644 --- a/docs/Features/XMLFeatures.md +++ b/docs/Features/XMLFeatures.md @@ -122,6 +122,12 @@ When XML file is associated with a DTD file, hover documentation based on tags, ![Hover Based On DTD](../images/Features/HoverBasedOnDTD.gif) +### Writing documentation for hover + +The documentation content in XSD (`xs:documentation`) and DTD (comments) supports HTML formatting that is automatically rendered as Markdown in the hover tooltip. This includes inline formatting (``, ``, ``), links, tables, lists, code blocks, and more. + +See [Writing Documentation for Hover Tooltips](../HoverDocumentation.md) for the full list of supported HTML elements and how to write documentation that renders well. + ## Validation Support ### Syntax validation diff --git a/docs/HoverDocumentation.md b/docs/HoverDocumentation.md new file mode 100644 index 00000000..2dd8d290 --- /dev/null +++ b/docs/HoverDocumentation.md @@ -0,0 +1,449 @@ +# Writing Documentation for Hover Tooltips + +LemMinX renders documentation from XSD (`xs:documentation`), DTD (comments), and RelaxNG (`a:documentation`) as **Markdown** in hover tooltips and completion details. HTML content in the documentation is automatically converted to Markdown. + +This page describes what HTML formatting is supported and how to write documentation that renders well in hover tooltips. + +## CDATA vs Entity Escaping + +To include HTML tags as documentation text in `xs:documentation`, you must either wrap the content in `` or escape the angle brackets with entities. Without one of these approaches, the XML parser treats tags like ``, `
`, or `` as XML elements rather than documentation content — they become part of the document structure instead of being passed to the hover renderer. + +### Using CDATA (recommended for complex HTML) + +Given this XSD: + +```xml + + + Configures the server connection.

+
+

See documentation.

+ ]]> + + +``` + +### Using entity escaping (for simple inline HTML) + +Given this XSD: + +```xml + + + + Configures the <b>server</b> connection. + + + +``` + +Both render the same in the hover: + +> Configures the **server** connection. + +### Common mistake + +Without CDATA or escaping, the XML parser treats HTML-like tags as markup rather than documentation text. Well-formed tags like `
` or `...` are valid XML, but they become XML elements in the document tree instead of being rendered in the hover tooltip. Truly malformed tags like `
` (without a closing slash or end tag) will also cause a parse error: + +```xml + + + Line 1
Line 2 + + + + + Line 1
Line 2 + +``` + +Correct alternatives: + +```xml + +Line 2]]> + + +Line 1<br>Line 2 +``` + +### DTD comments + +In DTD files, documentation is written as XML comments. CDATA is not available inside comments, so HTML tags must always be entity-escaped: + +```dtd + + + +``` + +Hover renders: + +> Configures the **server** connection. The `host` attribute specifies the hostname. + +### RelaxNG documentation + +In RelaxNG XML syntax (`.rng` files), documentation is written with `a:documentation` elements. Like XSD, you can use CDATA or entity escaping: + +```xml + + Configures the server connection.

+

See documentation for details.

+ ]]> + + +``` + +Hover renders: + +> Configures the **server** connection. +> +> See [documentation](https://example.com) for details. + +## Inline Formatting + +Given this XSD: + +```xml +bold and italic for emphasis. + The name attribute is deprecated. +]]> +``` + +Hover renders: + +> Use **bold** and *italic* for emphasis. The `name` attribute is ~~deprecated~~. + +Supported inline tags: + +| HTML | Rendered as | +| --- | --- | +| ``, `` | **bold** | +| ``, `` | *italic* | +| ``, `` | `code` | +| ``, `` | ~~strikethrough~~ | +| `
` | line break | + +## Links + +Given this XSD: + +```xml +XML Schema specification + for details. +]]> +``` + +Hover renders: + +> See [XML Schema specification](https://www.w3.org/TR/xmlschema-1/) for details. + +For URLs containing `&`, use `&` inside CDATA: + +```xml +search +]]> +``` + +## Images + +Given this XSD: + +```xml +Architecture overview:

+ Architecture diagram +]]> +``` + +Hover renders: + +> Architecture overview: +> +> ![Architecture diagram](https://example.com/arch.png) + +## Headings + +Given this XSD: + +```xml +Overview +

This element configures the application.

+

Required attributes

+

The name attribute must be specified.

+]]> +``` + +Hover renders: + +> ## Overview +> +> This element configures the application. +> +> ### Required attributes +> +> The `name` attribute must be specified. + +## Lists + +Given this XSD: + +```xml + +
  • Option A - the default
    • +
  • Option B - for advanced usage
    • + + Processing steps: +
      +
    1. Parse the input
      2. +
    2. Validate against schema
      3. +
    3. Transform output
      4. +
    +]]>     +``` + +Hover renders: + +> Available options: +> - Option A - the default +> - Option B - for advanced usage +> +> Processing steps: +> 1. Parse the input +> 2. Validate against schema +> 3. Transform output + +Nested lists are also supported: + +```xml + +
  • Category A +
      +
    • Sub-item A.1
      • +
    • Sub-item A.2
      • +
    +
    • +
  • Category B
    • + +]]>     +``` + +## Definition Lists + +Given this XSD: + +```xml + +
    timeout
    +
    Connection timeout in seconds
    +
    retries
    +
    Number of retry attempts
    + +]]>     +``` + +Hover renders: + +> **timeout** +> +> Connection timeout in seconds +> +> **retries** +> +> Number of retry attempts + +## Tables + +Given this XSD: + +```xml + +     + + +
    AttributeTypeDescription
    namestringThe element name
    typeQNameThe element type
    +]]> +``` + +Hover renders: + +> | Attribute | Type | Description | +> | --- | --- | --- | +> | name | string | The element name | +> | type | QName | The element type | + +The `colspan` attribute is supported for spanning columns. + +## Blockquotes + +Given this XSD: + +```xml + + Note: This element is deprecated since version 2.0. + Use new-element instead. + +]]> +``` + +Hover renders: + +> > Note: This element is deprecated since version 2.0. Use `new-element` instead. + +## Pre-formatted Code Blocks + +Given this XSD: + +```xml + +<server> + <host>localhost</host> +</server> + +]]> +``` + +Hover renders: + +> Example usage: +> +> ``` +> +> localhost +> +> ``` + +Inside `
    `, HTML formatting tags (``, ``, etc.) are ignored and content is preserved verbatim.
+
+## Markdown Fenced Code Blocks
+
+Documentation can use Markdown-style fenced code blocks directly. This is the natural way to show XML examples because tags inside the fence are **not** parsed as HTML.
+
+Given this XSD:
+
+````xml
+
+    localhost
+    8080
+
+```
+
+The above shows the default settings.
+]]>
+````
+
+Hover renders:
+
+> Example configuration:
+>
+> ```xml
+> 
+>     localhost
+>     8080
+> 
+> ```
+>
+> The above shows the default settings.
+
+Both `` ``` `` (backtick) and `~~~` (tilde) fence styles are supported. A closing fence must use the same character as the opening fence.
+
+## Mixing HTML and Fenced Code Blocks
+
+Given this XSD:
+
+````xml
+This element supports the following configuration:
    
+
+```xml
+
+    
+
+```
+
+    
+        
+        
+        
+    
    ModeDescription
    strictValidates all rules
    lenientIgnores unknown rules
    
+]]>    
+````
+
+Hover renders:
+
+> This element supports the following **configuration**:
+>
+> ```xml
+> 
+>     
+> 
+> ```
+>
+> | Mode | Description |
+> | --- | --- |
+> | strict | Validates all rules |
+> | lenient | Ignores unknown rules |
+
+## Unknown HTML Tags
+
+Tags that have no Markdown equivalent (such as ``, ``) are rendered contextually.
+
+Given this XSD:
+
+```xml
+ element is the root of Spring configuration.
+    Use  to set properties.
+]]>
+```
+
+Hover renders:
+
+> The `` element is the root of Spring configuration. Use `` to set properties.
+
+Tags inline with text are rendered as inline code. Tags alone on a line are rendered as fenced code blocks.
+
+## Transparent HTML Tags
+
+The following tags are recognized but produce no Markdown markers. Their content is rendered normally:
+
+``, `
    `, ``, ``, ``, ``, `
    `, `