Vue hydration issues caused by invalid HTML make page unscrollable after clicking on modal

[damithc]

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

#2008

Tell us about your environment

n/a

MarkBind version

4.0.1

What did you do? Describe the bug

--

Steps to reproduce

Go to https://nus-tic2002-ay2223s1.github.io/website/schedule/week5/topics.html#W5-5c
Click on the following modal link:

Expected behavior

Page should work normally.

Actual behavior

The modal doesn't have an X for closing, and the scrollbar of the parent page disappears even after closing the modal.

But no such problem in https://nus-cs2103-ay2223s1.github.io/website/schedule/week5/topics.html#implementation-refactoring-how

Anything else?

Both sites are slight variations of each other. The first is from the tic2002 branch while the latter is from the cs2103 branch of the same repo https://github.com/nus-cs2103/website-base
That said, the rest of the content of the page is very different between the two sites as the two module follows different topic orders.

TODO

d.easy

• make the docs more visible by linking it in the modal section, as this has happened quite often when using modals

d.moderate (explore and implement one or all of the solutions proposed:
See #2025 (comment)

• Check out how other vue-based tools like vuepress / nuxt does it
• Implementing some simple rules ourselves (e.g. tables)
• Bringing in some external binary to validate the outputs

[damithc]

Another one nus-cs2103-AY2223S1/forum#109

[yixiann]

I am facing the same issue at:

https://nus-cs2103-ay2223s1.github.io/website/schedule/week5/topics.html#supplementary-requirements

In the sentence:
A supplementary requirements section can be used to capture requirements that do not fit elsewhere. Typically, this is where most Non-Functional Requirements will be listed.

After clicking
"Non-Functional Requirements"

[tlylt]

I am facing the same issue at:

Thanks @yixiann for the bug report!

Hi @damithc, looks like it could be due to Vue hydration issues caused by invalid HTML. There were a few tables referenced in the problematic pages where the <table> does not contain a <tbody> (functionally, this is fine and doesn't really do much, but for Vue it needs the HTML semantic to be correct), which seems to distort the functionality of the modal.

This is not a problem for other pages either because they don't contain such tables, or they use tables that are generated from markdown (which we will handle the HTML generation).

The offending tables are e.g.:

They are typically used for set code block side by side, like:

In SE book itself, I found 13 places of such issues (search for </table>), fixing them manually (by appending <tbody> and </tbody> within <table> and the modal starts to work as expected again.

Related to:
#572

[damithc]

@tlylt thanks very much for the investigation and figuring out the solution. Seems to work when I tried it. Will update all <table>s lacking the <tbody> tag.

[ang-zeyu]

Great investigation! @tlylt

I can't remember where I mentioned it but again we can also consider introducing some build time validation for these common violations:

• Implementing some simple rules ourselves (e.g. tables)
• Bringing in some external binary to validate the outputs
• Checkout how other vue-based tools like vuepress / nuxt does it

[damithc]

One more case that is not inside a table.

https://nus-cs2103-ay2223s1.github.io/website/schedule/week7/topics.html

[jonahtanjz]

One more case that is not inside a table.

https://nus-cs2103-ay2223s1.github.io/website/schedule/week7/topics.html

Looks like on the same page there is 1 more <table> without a <thead> and <tbody> leading to hydration issue. Running the site in development mode will show these errors in the console:

Should be this particular table under https://nus-cs2103-ay2223s1.github.io/website/schedule/week7/topics.html#project-management-project-planning-work-breakdown-structure

https://github.com/se-edu/se-book/blob/ba0b92d28e14fda03acddd8d98bcba29be9cbb8e/projectPlanning/workBreakdownStructure/text.md?plain=1#L33

[damithc]

Looks like on the same page there is 1 more <table> without a <thead> and <tbody> leading to hydration issue. Running the site in development mode will show these errors in the console:

Thanks for the investigation @jonahtanjz 💯
It seems I missed a few <table> elements because my regular expression find-and-replace didn't account for the <table> element having attributes. Fixed now.

[WillCWX]

Is this issue closable? Or is there a more desired fix other than making sure that there are no more invalid html leading to hydration issues and component malfunction? (or are we keeping this issue open to reference to for other similar issues)

[tlylt]

Is this issue closable? Or is there a more desired fix other than making sure that there are no more invalid html leading to hydration issues and component malfunction? (or are we keeping this issue open to reference to for other similar issues)

We already have a troubleshooting section on this issue (not fully explained but included a note on missing tbody) here

• perhaps can make the Docs more visible by linking it in the modal section, as this has happened quite often when using modals

Will edit the issue to include the TODOs mentioned in #2025 (comment)

[yiwen101]

I would like to clarify the concept of hydration.
I am working on adding simple rules to detect invalid html structure. One of the rule is that "

" tag can not have block level element as children, and it detects that (to my surprise) 404.md violates the rule.

In 404.vue.js:

In 404.html:

String value of "content" in runtime:

However, when I do "markbind serve -d" at /docs, I do not experience/see hydration issue. Why is this the case?

[tlylt]

I would like to clarify the concept of hydration.

I am working on adding simple rules to detect invalid html structure. One of the rule is that "

" tag can not have block level element as children, and it detects that (to my surprise) 404.md violates the rule.

I am not sure why but I do observe this as well. Seems to suggest that some violations (e.g p contains doc ) are "tolerated" while some violations (e.g missing tbody in table) are always (?) reported. Can verify again using https://validator.w3.org to check the syntax

I would suggest doing abit more googling to find out...could be due to how browsers implement the HTML spec as well.

[WillCWX]

It seems that different browsers have different ways and efforts to fix invalid HTML, resulting in the difference between the original html and the html displayed in the browser.

From MDM Web Docs: Permissive Code

Browsers have built-in rules to state how to interpret incorrectly written markup, so you'll get something running, even if it is not what you expected. This, of course, can still be a problem!

So it seems that any violations that can be fixed by the browsers' built-in rules will be "tolerated".
However, this is still undesirable as the fix may alter the look of the page unexpectedly and not all browsers maybe able to fix the specific violation.

[yiwen101]

@tlylt @WillCWX
Thank you for the detailed clarification and providing valuable add-on information. I will explore into the topic further.

[yiwen101]

After some primitive testing, it seems that current browsers are quite robust. All the issues listed below seems would not cause hydration issue (though may still leads to unexpected behaviours):

Missing remains the only known violation that (always?) leads to hydration issue.

[kaixin-hc]

This should be addressed by yiwen101's PR to make this easier to prevent and fix in the future. Let's close this issue for now unless it resurfances.