Fix unexpected behavior in UG due to invalid HTML markup

[tlylt]

What is the purpose of this pull request?

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• Others, please explain:

Overview of changes:
Fixes #1794
Also fixes #1840 (very much related so putting it together here)

• Include a 'troubleshooting' section in UG for putting such errors

Anything you'd like to highlight / discuss:
Not too sure why, but sometimes it's fine for block-level elements to be in <span> but sometimes not.
E.g. in embed section, seems like this span tag works fine and does not trigger any vue warning.

Testing instructions:

• verify the behavior according to issue Unexpected siteNav scrolling effect on small screens #1794
• preview the added section

Proposed commit message: (wrap lines at 72 characters)
Fix unexpected behavior in UG due to invalid HTML markup

Invalid HTML markup may cause Vue hydration issues.

Let's replace span tags with div tags to avoid invalid
inclusion of block-level elements in span tags.

This prevents possible errors in HTML syntax.

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

[ryoarmanda]

Interesting issue 👀 I'm also a bit intrigued on the embed case, maybe the issue is for specific block-level elements like tables? (cc @jonahtanjz) I think we can also change those to use div for posterity sake, what do you think?

The docs you have written up are a good start, maybe some little stylization nits below:

[jonahtanjz]

I'm also a bit intrigued on the embed case, maybe the issue is for specific block-level elements like tables? (cc @jonahtanjz)

Having block elements within inline elements should not be allowed according to the SSR guide for Vue. For some reason, Vue does not always warn or have issues with some of the cases.

For example, putting the following code on a MarkBind site,

<span>
<div>Test</div>
</span>

doesn't seem to have any warnings.

Similarly, even using the example provided on Vue's page,

<p>
<div>Test</div>
</p>

no warnings as well.

Putting a table in a <span> seems to consistently cause the warning to show up.

The following seems to cause the warning to show up as well,

<p>
<ul>
<li>1</li>
<li>2</li>
</ul>
</p>

I think we can also change those to use div for posterity sake, what do you think?

Although some of the offending components don't result in any warnings, I think they should still be changed as well since they are not valid HTML and may cause some problematic issues in the future.

[jonahtanjz]

Thanks @tlylt!

A couple more invalid HTML:

• docs/index.md#19 (<p> in <span>)
• docs/userGuide/addingPages.md#17 (<p> in <span>)
• docs/userGuide/deployingTheSite.md#17 (<p> in <span>)
• docs/userGuide/formattingContents.md#17 (<p> in <span>)
• docs/userGuide/makingTheSiteSearchable.md#19 (<p> in <span>)
• docs/userGuide/markBindInTheProjectWorkflow.md#16 (<p> in <span>)
• docs/userGuide/markBindSyntaxOverview.md#17 (<p> in <span>)
• docs/userGuide/reusingContents.md#17 (<p> in <span>)
• docs/userGuide/siteJsonFile.md#10 (<p> in <span>)
• docs/userGuide/themes.md#16 (<p> in <span>)
• docs/userGuide/usingHtmlJavaScriptCss.md#34 (example used is not valid HTML as it will create a <p> in <span>)
• docs/userGuide/syntax/tree.md#96 and #110 (codeblock and <tree> in <span>)
• docs/userGuide/syntax/popovers.md#48 (<div> in <p>)

Also noticed a few of our Vue components having block-level elements in <span>. This can be fixed in another PR.

Popover.vue
MinimalPanel.vue
NestedPanel.vue

[tlylt]

A couple more invalid HTML:

Good catch! I have fixed the cases mentioned. I also:

• added one warning in the reusing content -> includes section to inform users to choose div over span
• removed some span to div replacement as those spans within a boilerplate appear to be important for the variable to work. Will open a separate issue for this.

[jonahtanjz]

Thanks @tlylt! Looks good to me 👍

Let's wait for @ryoarmanda to look through and approve as well :)

[ryoarmanda]

Looks good to me as well! Will merge tonight

[ryoarmanda]

Some weird thing happening here 🤔 the checks have been in queue for a while now, and I didn't see it ever running. Even the checks tab show 0 checks, and no workflow records appear.

If this keeps going, I might have to close and reopen this PR to kick the checks back up again.

[tlylt]

Some weird thing happening here 🤔 the checks have been in queue for a while now, and I didn't see it ever running. Even the checks tab show 0 checks, and no workflow records appear.

If this keeps going, I might have to close and reopen this PR to kick the checks back up again.

GitHub is experiencing some operational error, we can probably wait out.

[jonahtanjz]

If this keeps going, I might have to close and reopen this PR to kick the checks back up again.

Will need to try this since it is still stuck in queue.

[ryoarmanda]

Okay, checks are running now.