Add documentation on troubleshooting rendering markdown

* Update trouble shooting * Update code examples in affected presentation components * Update message for presentation component * Revert unrelated changes * Fix links * Update docs/userGuide/components/presentation.md Co-authored-by: Chan Yu Cheng <[email protected]> * Revert distracting changes made by formatter * Revert distracting changes by formatter2 * Migrate to codeAndOutput * Updade doc * Update presentation.md * Update ug * Clean formatting error * Proof read * Improve formatting * Improve format * Improve format * Update troubleshooting.md * Update troubleshooting.md --------- Co-authored-by: Chan Yu Cheng <[email protected]>
MarkBind · Feb 12, 2024 · 7d9cf5a · 7d9cf5a
1 parent a6ef6cc
commit 7d9cf5a
Show file tree

Hide file tree

Showing 6 changed files with 81 additions and 10 deletions.
diff --git a/docs/userGuide/components/presentation.md b/docs/userGuide/components/presentation.md
@@ -20,6 +20,15 @@
 
 The components in this page are the core **presentational** components you may want to use. Panels and tabs can be used to **organise content sections**, while badges and boxes can **highlight small, specific pieces of information**.
 </div>
+<box type = "warning" header = "#### Use of markdown in content" >
+
+As presentational components are HTML-based, you need to follow the HTML syntax when using markdown in the content of the components.
+More specifically, you should use either:
+- add a line break with no indentation before the markdown content
+- use the `<markdown>` (block level elements) or `<md>` (inline level elements) tags to wrap the markdown content.
+
+For more information, please refer to this [section]({{baseUrl}}/userGuide/usingHtmlJavaScriptCss.html#markdown-in-html).
+</box>
 
 {% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %}
 

diff --git a/docs/userGuide/syntax/badges.md b/docs/userGuide/syntax/badges.md
@@ -1,5 +1,20 @@
 ## Badges
 
+**Example:**
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<span class="badge bg-primary">
+Some Plain Text
+</span>
+
+<span class="badge bg-primary">
+<md>_Some Markdown_</md>
+</span>
+</variable>
+</include>
+
+**You can choose from a variety of colors for your badges.  You can also use the `rounded-pill` class to make the badges pill-shaped.**
 <include src="codeAndOutput.md" boilerplate >
 <variable name="highlightStyle">html</variable>
 <variable name="code">
@@ -24,7 +39,7 @@ Normal:
 </variable>
 </include>
 
-You can use Badges in combination with headings, buttons, links, etc.
+**You can use Badges in combination with headings, buttons, links, etc.**
 
 <include src="codeAndOutput.md" boilerplate >
 <variable name="highlightStyle">html</variable>

diff --git a/docs/userGuide/syntax/boxes.md b/docs/userGuide/syntax/boxes.md
@@ -2,14 +2,25 @@
 
 ## Boxes
 
-**Boxes come with different built-in types.**
-
+**Simple Example**
 <include src="codeAndOutput.md" boilerplate >
 <variable name="highlightStyle">html</variable>
 <variable name="code">
 <box>
-    default
+plain text
 </box>
+
+<box>
+<md>_markdown_</md>
+</box>
+</variable>
+</include>
+
+**Boxes come with different built-in types.**
+
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
 <box type="info">
     info
 </box>
@@ -50,9 +61,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 <include src="codeAndOutput.md" boilerplate >
 <variable name="highlightStyle">html</variable>
 <variable name="code">
-<box>
-    default
-</box>
 <box type="info" theme="primary">
     primary
 </box>

diff --git a/docs/userGuide/syntax/panels.md b/docs/userGuide/syntax/panels.md
@@ -8,7 +8,8 @@
 <variable name="highlightStyle">html</variable>
 <variable name="code">
 <panel header="This is your header for a Panel, click me to expand!">
-  Lorem ipsum ...
+<markdown>_markdown_</markdown>
+plain text ...
 </panel>
 </variable>
 </include>

diff --git a/docs/userGuide/syntax/tabs.md b/docs/userGuide/syntax/tabs.md
@@ -5,7 +5,8 @@
 <variable name="code">
 <tabs>
   <tab header="First tab">
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla ullamcorper ultrices lobortis.
+    Text in the first tab
+    <markdown>_some markdown_</markdown>
   </tab>
   <tab header="Disabled second tab :x:" disabled>
   </tab>

diff --git a/docs/userGuide/troubleshooting.md b/docs/userGuide/troubleshooting.md
@@ -30,7 +30,7 @@ Cats   |    yes     |   100 |
 </span>
 ```
 
-The table specified by the markdown syntax above will be rendered as a block-level element, which will be included in a inline span element. This makes the HTML output invalid.
+The table specified by the Markdown syntax above will be rendered as a block-level element, which will be included in a inline span element. This makes the HTML output invalid.
 
 <panel header="Underlying Error (Example)" type="seamless">
 
@@ -57,3 +57,40 @@ Cats   |    yes     |   100 |
 </div>
 ```
 
+##### Markdown Rendering Issues
+
+If you encounter issues in rendering Markdown in a component, it is likely that the Markdown is not being properly recognized due to syntax errors. Signposting is required to inform Markdown to parse the content of a presentation component as Markdown rather than plain text.
+
+You could signpost Markdown either by:
+
+- using the `<markdown>`(block level elements) or `<md>`(inline level elements) tags to wrap the Markdown content.
+- using an empty line without any indentation before the Markdown content
+
+###### Example: correct Markdown rendering using tags or newline:
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<box>
+
+**Example1**
+</box>
+
+<box> 
+<md> **Example2** </md> 
+</box>
+
+<box> 
+<markdown> **Example3** </markdown> 
+</box>
+
+
+</variable>
+</include>
+<panel header="###### Example: Markdown not rendered without singposting" type="seamless">
+<include src="codeAndOutput.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<box> **This will be rendered as plain text**</box>
+</variable>
+</include>
+</panel>