From 7d9cf5a1aff00079400f020a71ad03332dc6d8f8 Mon Sep 17 00:00:00 2001 From: Wang Yiwen <121547057+yiwen101@users.noreply.github.com> Date: Mon, 12 Feb 2024 21:58:30 +0800 Subject: [PATCH] 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 <77204346+yucheng11122017@users.noreply.github.com> * 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 <77204346+yucheng11122017@users.noreply.github.com> --- docs/userGuide/components/presentation.md | 9 ++++++ docs/userGuide/syntax/badges.md | 17 +++++++++- docs/userGuide/syntax/boxes.md | 20 ++++++++---- docs/userGuide/syntax/panels.md | 3 +- docs/userGuide/syntax/tabs.md | 3 +- docs/userGuide/troubleshooting.md | 39 ++++++++++++++++++++++- 6 files changed, 81 insertions(+), 10 deletions(-) diff --git a/docs/userGuide/components/presentation.md b/docs/userGuide/components/presentation.md index b86565eb95..c743f81b59 100644 --- 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**. + + +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 `` (block level elements) or `` (inline level elements) tags to wrap the markdown content. + +For more information, please refer to this [section]({{baseUrl}}/userGuide/usingHtmlJavaScriptCss.html#markdown-in-html). + {% from "userGuide/fullSyntaxReference.md" import syntax_topics as topics %} diff --git a/docs/userGuide/syntax/badges.md b/docs/userGuide/syntax/badges.md index 59b1d78e93..73f8a24692 100644 --- a/docs/userGuide/syntax/badges.md +++ b/docs/userGuide/syntax/badges.md @@ -1,5 +1,20 @@ ## Badges +**Example:** + +html + + +Some Plain Text + + + +_Some Markdown_ + + + + +**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.** html @@ -24,7 +39,7 @@ Normal: -You can use Badges in combination with headings, buttons, links, etc. +**You can use Badges in combination with headings, buttons, links, etc.** html diff --git a/docs/userGuide/syntax/boxes.md b/docs/userGuide/syntax/boxes.md index ff2c95d2a7..e7c78a8389 100644 --- 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** html - default +plain text + + +_markdown_ + + + + +**Boxes come with different built-in types.** + + +html + info @@ -50,9 +61,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i html - - default - primary diff --git a/docs/userGuide/syntax/panels.md b/docs/userGuide/syntax/panels.md index 663e8ee9d1..485f52a67e 100644 --- a/docs/userGuide/syntax/panels.md +++ b/docs/userGuide/syntax/panels.md @@ -8,7 +8,8 @@ html - Lorem ipsum ... +_markdown_ +plain text ... diff --git a/docs/userGuide/syntax/tabs.md b/docs/userGuide/syntax/tabs.md index 97adfa7265..e24ac2a048 100644 --- a/docs/userGuide/syntax/tabs.md +++ b/docs/userGuide/syntax/tabs.md @@ -5,7 +5,8 @@ - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla ullamcorper ultrices lobortis. + Text in the first tab + _some markdown_ diff --git a/docs/userGuide/troubleshooting.md b/docs/userGuide/troubleshooting.md index 1b3924f5aa..51048d2d39 100644 --- a/docs/userGuide/troubleshooting.md +++ b/docs/userGuide/troubleshooting.md @@ -30,7 +30,7 @@ Cats | yes | 100 | ``` -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. @@ -57,3 +57,40 @@ Cats | yes | 100 | ``` +##### 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 ``(block level elements) or ``(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: + +html + + + +**Example1** + + + + **Example2** + + + + **Example3** + + + + + + + +html + + **This will be rendered as plain text** + + + \ No newline at end of file