From fbd4c50050c56f95c08d5a2845591dfb6334d61b Mon Sep 17 00:00:00 2001 From: azerr Date: Tue, 20 Oct 2026 09:32:32 +0200 Subject: [PATCH] Add documentation for hover tooltip HTML rendering Describe all supported HTML elements (inline formatting, links, images, headings, lists, tables, blockquotes, pre blocks, fenced code blocks) and the CDATA vs entity escaping requirement for xs:documentation. Signed-off-by: azerr --- docs/Features/XMLFeatures.md | 6 + docs/HoverDocumentation.md | 449 +++++++++++++++++++++++++++++++++++ 2 files changed, 455 insertions(+) create mode 100644 docs/HoverDocumentation.md 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:
+
+``, `
    `, ``, ``, ``, ``, `
    `, `