docs(markdown): update Markdown documentation with new references

- Added reference to Markdown Syntax & Extensions in using-markdown.md
- Clarified Markdown Editor Reference with additional details
- Enhanced markdown-examples.md with links to relevant documentation

Author: christophe-g

docs/app/survey/explanation/understanding-css-variables.md

@@ -20,16 +20,16 @@ If you change the value of `--primary-color` in one place, every element using t
 
 ## How Accessible Surveys Uses CSS Variables
 
-Accessible Surveys relies heavily on CSS variables to drive its styling and accessibility features. 
+Accessible Surveys relies heavily on CSS variables to drive its styling and accessibility features.
 
 ### 1. Dynamic Theming
 When you configure the primary color or font of your survey in the styling editor, you aren't writing new CSS rules from scratch. Instead, you are updating the underlying CSS variables for the survey. The entire application layout references these variables, meaning your changes cascade instantly and consistently across buttons, headers, borders, and backgrounds.
 
 ### 2. Accessibility Modes (Dark, High Contrast)
-Our commitment to accessibility requires the interface to adapt to the user's needs on the fly. 
-When a respondent switches to **Dark Mode** or **High Contrast Mode**, the platform simply swaps out the color palette assigned to the CSS variables. 
+Our commitment to accessibility requires the interface to adapt to the user's needs on the fly.
+When a respondent switches to **Dark Mode** or **High Contrast Mode**, the platform simply swaps out the color palette assigned to the CSS variables.
 
 Because the underlying CSS structure uses variables like `--text-color` and `--background-color` instead of hardcoded values (like `black` or `white`), the survey can instantly invert or heighten contrast without needing a completely separate stylesheet for every theme.
 
 ### 3. Responsive Overrides
-Variables also make it easy to adjust sizing based on the screen size (responsive design). We use variables to control padding and margins, which shrink automatically on mobile devices to ensure a comfortable reading experience.
+Variables also make it easy to adjust sizing based on the screen size (responsive design). We use variables to control padding and margins, which shrink automatically on mobile devices to ensure a comfortable reading experience.

docs/app/survey/explanation/using-markdown.md

@@ -39,5 +39,7 @@ In a platform dedicated to accessibility and robust data collection, the structu
 ---
 
 **See also:**
+
 * [How-to: Providing Rich Formatting](../how-to/providing-rich-formatting.md)
+* [Reference: Markdown Syntax & Extensions](../reference/content/markdown/index.md)
 * [Reference: Rich Text Editor Component](../../../components/md-editor.md)

docs/app/survey/how-to/styling-a-survey.md

@@ -4,7 +4,7 @@ description: Learn how to customize the visual appearance of your survey, includ
 
 # Styling a Survey
 
-Accessible Surveys provides a robust styling engine that allows you to customize the look and feel of your survey to match your brand while maintaining strict accessibility standards. 
+Accessible Surveys provides a robust styling engine that allows you to customize the look and feel of your survey to match your brand while maintaining strict accessibility standards.
 
 Because respondents can switch between high-contrast, dark, and light modes via the accessibility menu, the styling tools are designed to adapt automatically. This ensures your survey remains beautiful and legible regardless of the active accessibility mode.
 
@@ -22,7 +22,7 @@ To access the styling options, you need to open the survey builder's **Behavior*
 
 ## Step 2: Configure Styling Options
 
-The styling panel gives you access to various customization parameters. 
+The styling panel gives you access to various customization parameters.
 
 1. Expand the styling sections to access the configuration tools.
 2. Adjust the settings to match your desired aesthetic.
@@ -34,9 +34,10 @@ The styling panel gives you access to various customization parameters.
 
 ### Available Styling Controls
 While exact options may vary based on your plan, you typically have control over:
-*   **Primary Colors**: Set the main brand color used for buttons, active states, and highlights.
-*   **Typography**: Choose a base font family that is legible and web-safe.
-*   **Layout Elements**: Control spacing, borders, and general alignment.
+
+* **Primary Colors**: Set the main brand color used for buttons, active states, and highlights.
+* **Typography**: Choose a base font family that is legible and web-safe.
+* **Layout Elements**: Control spacing, borders, and general alignment.
 
 ::: tip
 **Accessibility First**
@@ -45,7 +46,7 @@ When you select a primary color, the platform automatically calculates appropria
 
 ## Step 3: Responsive Overrides (Optional)
 
-You can also provide specific styling overrides based on how the respondent interacts with the survey. 
+You can also provide specific styling overrides based on how the respondent interacts with the survey.
 
 For example, you can adjust padding or layout styles specifically for **small screens** (mobile devices), or define how the layout behaves when the survey is set to display **one question per page**. These overrides ensure the user experience is optimized for every context.
 
@@ -60,6 +61,6 @@ Always switch to the **Test** view to see how your styles look in a real environ
 ## References
 
 For more detailed technical information on how styling properties are managed and applied behind the scenes, please refer to:
-- [Reference: Behavior Settings](../reference/build/behavior.md)
-- [Reference: Customer Theme](../../customer/reference/customer/theme.md)
-- [Explanation: Understanding CSS Variables](../explanation/understanding-css-variables.md)
+* [Reference: Behavior Settings](../reference/build/behavior.md)
+* [Reference: Customer Theme](../../customer/reference/customer/theme.md)
+* [Explanation: Understanding CSS Variables](../explanation/understanding-css-variables.md)

docs/app/survey/reference/content/markdown/index.md

@@ -2,10 +2,14 @@
 description: Reference documentation for the Markdown editor and supported syntax extensions.
 ---
 
-# Markdown Editor
+# Markdown Editor Reference
 
 The Markdown Free Text field in Accessible Surveys supports standard Markdown syntax along with custom HTML, CSS tokens, convenience classes, and embedded web components.
 
+::: info
+This reference focuses on the technical syntax and advanced styling available when writing Markdown and HTML manually. If you are looking for documentation on the visual editor toolbar, formatting shortcuts, and interactive widgets, please see the [Shared Components: Rich Text Editor](../../../../../components/md-editor.md) documentation.
+:::
+
 ## Supported Syntax
 
 * **Standard Markdown:** Basic formatting (bold `**text**`, italic `*text*`), headings (`#`, `##`), lists, and tables. See the [Markdown Guide](https://www.markdownguide.org/basic-syntax/).
@@ -51,3 +55,32 @@ The editor environment includes built-in classes and variables to integrate user
   }
 </style>
 ```
+
+### Understanding the Example
+
+The code snippet above demonstrates how standard Markdown, raw HTML, convenience classes, accessibility modifiers, web components, and CSS tokens can all be combined into a single, cohesive block of text. Here is a breakdown of how it works:
+
+#### 1. Layout and Spacing (Convenience Classes)
+The outer container uses `<div class="layout horizontal wrap gap">`.
+
+* `layout horizontal` and `wrap` are built-in **Convenience Classes** that turn the container into a flexbox layout. Items will sit side-by-side (horizontally) and wrap to the next line if the screen is too small.
+* The child elements use the `flex` and `flex-2` classes. This means the third column (`flex-2`) will automatically take up twice as much horizontal space as the other columns (`flex`).
+
+#### 2. Conditional Display (Accessibility Modes)
+The first two child `<div>` elements include the `show-when-signlanguage` and `show-when-easyread` classes.
+
+* These are **Accessibility Mode** modifiers. The platform's rendering engine listens to the user's active settings. The first block of text will *only* be visible if the respondent has enabled Sign Language mode, while the second is exclusively for Easy Read mode.
+
+#### 3. Mixing HTML and Markdown
+Notice that inside the HTML `<div>` tags, standard Markdown syntax like `**sign language mode**` is used freely to create bold text.
+
+#### 4. Web Components
+Instead of pasting a messy iframe from YouTube, the editor supports custom **Web Components**.
+
+* The `<lite-youtube videoid="xVytWVHX4N0"></lite-youtube>` tag creates a highly optimized, accessible video player simply by providing the video ID.
+
+#### 5. Theming (CSS Tokens)
+Finally, a `<style>` block is included to define the custom `.box` and `.gap` classes.
+
+* Instead of hardcoding colors (e.g., `background-color: blue`), it uses **CSS Tokens** like `var(--color-primary)` and `var(--color-on-primary)`.
+* If the survey is viewed in Dark Mode, or if the Customer Theme defines a different primary brand color, these variables update automatically. This ensures the custom styling remains accessible and visually consistent without requiring manual media queries.

docs/markdown-examples.md

@@ -1,6 +1,15 @@
 # Markdown Extension Examples
 
-This page demonstrates some of the built-in markdown extensions provided by VitePress.
+This page demonstrates some of the built-in markdown extensions provided by the VitePress documentation engine itself (this is used for writing *these* docs, rather than the Markdown used in the actual Survey App).
+
+::: info
+If you are looking for documentation on how Markdown is used within the Accessible Surveys application, please see:
+
+* [Explanation: Using Markdown](./app/survey/explanation/using-markdown.md)
+* [How-to: Providing Rich Formatting](./app/survey/how-to/providing-rich-formatting.md)
+* [Reference: Markdown Syntax & Extensions](./app/survey/reference/content/markdown/index.md)
+* [Shared Component: Rich Text Editor](./components/md-editor.md)
+:::
 
 ## Syntax Highlighting