Skip to content

Update Developer Guide on SSR based on feedback#1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ang-zeyu merged 6 commits into from
Jun 16, 2021
Merged

Update Developer Guide on SSR based on feedback #1573

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cc2cfb3
Update SSR Guide
wxwxwxwx9 Jun 5, 2021
913485d
Add full stop
wxwxwxwx9 Jun 5, 2021
ee47c97
Update according to review
wxwxwxwx9 Jun 5, 2021
c103475
Update serverSideRendering.md
wxwxwxwx9 Jun 6, 2021
b943064
Update serverSideRendering.md
wxwxwxwx9 Jun 6, 2021
e5f5c3a
Update serverSideRendering.md
wxwxwxwx9 Jun 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 27 additions & 7 deletions docs/devGuide/design/serverSideRendering.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,11 @@

<div class="lead">

MarkBind makes use of Server-side Rendering (SSR) for its pages.
MarkBind uses Server-side Rendering (SSR) for its pages.

To ensure SSR works properly, there are certain rules that developers should adhere to.

This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind.
This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind.
</div>

## Pre-requisite Knowledge
Expand All@@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue:
- Are there any differences between compiling Vue on client-side versus server-side?
- What is the difference between compiling and rendering?

### MarkBind's Packages
<box type="info" header="##### Useful Resources to understand Vue better" seamless>

If there are any doubts regarding the questions above, here are some good resources to refer to:

- [Vue Official Documentation](https://vuejs.org/v2/guide)
- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU)
</box>

### Understanding MarkBind's Packages

There are four packages in MarkBind's codebase:
1. cli
Expand All@@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance

SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML.

During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.
During the hydration process, Vue essentially compares your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.

This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind.

<box type="warning" header="#### Using production build" seamless>

In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option).
</box>

## Penalties of Hydration Issue

When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards).
Expand All@@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c
Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application".

It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things:
1) the state data are the same between client-side and server-side.
1) the initial state is the same between client-side and server-side.
2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.

However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue:
- Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag).
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to.

Some common mistakes are as such:
- Having block-level elements within `<p>` tag
- Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation).

<box type="success" seamless>

If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
Comment thread
wxwxwxwx9 marked this conversation as resolved.
</box>

Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Update Developer Guide on SSR based on feedback by wxwxwxwx9 · Pull Request #1573 · MarkBind/markbind · GitHub
Skip to content
Update Developer Guide on SSR based on feedback#1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ang-zeyu
merged 6 commits into

from

Jun 16, 2021
 Merged


Update Developer Guide on SSR based on feedback
#1573
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cc2cfb3

Update SSR Guide


wxwxwxwx9 Jun 5, 2021
913485d

Add full stop


wxwxwxwx9 Jun 5, 2021
ee47c97

Update according to review


wxwxwxwx9 Jun 5, 2021
c103475

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
b943064

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
e5f5c3a

Update serverSideRendering.md


wxwxwxwx9 Jun 13, 2021

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


34 changes: 27 additions & 7 deletions
docs/devGuide/design/serverSideRendering.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,11 @@

<div class="lead">

MarkBind makes use of Server-side Rendering (SSR) for its pages. 
MarkBind uses Server-side Rendering (SSR) for its pages. 

To ensure SSR works properly, there are certain rules that developers should adhere to. 

This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind. 
This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind. 
</div>

## Pre-requisite Knowledge
Expand All@@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue:
- Are there any differences between compiling Vue on client-side versus server-side?
- What is the difference between compiling and rendering?

### MarkBind's Packages
<box type="info" header="##### Useful Resources to understand Vue better" seamless>

If there are any doubts regarding the questions above, here are some good resources to refer to:

- [Vue Official Documentation](https://vuejs.org/v2/guide)
- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU)
</box>

### Understanding MarkBind's Packages

There are four packages in MarkBind's codebase:
1. cli
Expand All@@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance

SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML.

During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.
During the hydration process, Vue essentially compares your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.

This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. 

<box type="warning" header="#### Using production build" seamless>

In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option).
</box>

## Penalties of Hydration Issue

When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards).
Expand All@@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c
Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". 

It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things:
1) the state data are the same between client-side and server-side.
1) the initial state is the same between client-side and server-side.
2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.

However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue: 
- Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag).
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. 

Some common mistakes are as such: 
- Having block-level elements within `<p>` tag
- Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation). 

<box type="success" seamless>

If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
Comment thread
wxwxwxwx9 marked this conversation as resolved.

</box>

Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Update Developer Guide on SSR based on feedback by wxwxwxwx9 · Pull Request #1573 · MarkBind/markbind · GitHub
Skip to content
Update Developer Guide on SSR based on feedback#1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ang-zeyu
merged 6 commits into

from

Jun 16, 2021
 Merged


Update Developer Guide on SSR based on feedback
#1573
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cc2cfb3

Update SSR Guide


wxwxwxwx9 Jun 5, 2021
913485d

Add full stop


wxwxwxwx9 Jun 5, 2021
ee47c97

Update according to review


wxwxwxwx9 Jun 5, 2021
c103475

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
b943064

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
e5f5c3a

Update serverSideRendering.md


wxwxwxwx9 Jun 13, 2021

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


34 changes: 27 additions & 7 deletions
docs/devGuide/design/serverSideRendering.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,11 @@

<div class="lead">

MarkBind makes use of Server-side Rendering (SSR) for its pages. 
MarkBind uses Server-side Rendering (SSR) for its pages. 

To ensure SSR works properly, there are certain rules that developers should adhere to. 

This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind. 
This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind. 
</div>

## Pre-requisite Knowledge
Expand All@@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue:
- Are there any differences between compiling Vue on client-side versus server-side?
- What is the difference between compiling and rendering?

### MarkBind's Packages
<box type="info" header="##### Useful Resources to understand Vue better" seamless>

If there are any doubts regarding the questions above, here are some good resources to refer to:

- [Vue Official Documentation](https://vuejs.org/v2/guide)
- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU)
</box>

### Understanding MarkBind's Packages

There are four packages in MarkBind's codebase:
1. cli
Expand All@@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance

SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML.

During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.
During the hydration process, Vue essentially compares your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.

This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. 

<box type="warning" header="#### Using production build" seamless>

In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option).
</box>

## Penalties of Hydration Issue

When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards).
Expand All@@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c
Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". 

It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things:
1) the state data are the same between client-side and server-side.
1) the initial state is the same between client-side and server-side.
2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.

However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue: 
- Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag).
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. 

Some common mistakes are as such: 
- Having block-level elements within `<p>` tag
- Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation). 

<box type="success" seamless>

If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
Comment thread
wxwxwxwx9 marked this conversation as resolved.

</box>

Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Update Developer Guide on SSR based on feedback by wxwxwxwx9 · Pull Request #1573 · MarkBind/markbind · GitHub
Skip to content
Update Developer Guide on SSR based on feedback#1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ang-zeyu
merged 6 commits into

from

Jun 16, 2021
 Merged


Update Developer Guide on SSR based on feedback
#1573
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cc2cfb3

Update SSR Guide


wxwxwxwx9 Jun 5, 2021
913485d

Add full stop


wxwxwxwx9 Jun 5, 2021
ee47c97

Update according to review


wxwxwxwx9 Jun 5, 2021
c103475

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
b943064

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
e5f5c3a

Update serverSideRendering.md


wxwxwxwx9 Jun 13, 2021

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


34 changes: 27 additions & 7 deletions
docs/devGuide/design/serverSideRendering.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,11 @@

<div class="lead">

MarkBind makes use of Server-side Rendering (SSR) for its pages. 
MarkBind uses Server-side Rendering (SSR) for its pages. 

To ensure SSR works properly, there are certain rules that developers should adhere to. 

This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind. 
This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind. 
</div>

## Pre-requisite Knowledge
Expand All@@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue:
- Are there any differences between compiling Vue on client-side versus server-side?
- What is the difference between compiling and rendering?

### MarkBind's Packages
<box type="info" header="##### Useful Resources to understand Vue better" seamless>

If there are any doubts regarding the questions above, here are some good resources to refer to:

- [Vue Official Documentation](https://vuejs.org/v2/guide)
- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU)
</box>

### Understanding MarkBind's Packages

There are four packages in MarkBind's codebase:
1. cli
Expand All@@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance

SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML.

During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.
During the hydration process, Vue essentially compares your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.

This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. 

<box type="warning" header="#### Using production build" seamless>

In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option).
</box>

## Penalties of Hydration Issue

When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards).
Expand All@@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c
Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". 

It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things:
1) the state data are the same between client-side and server-side.
1) the initial state is the same between client-side and server-side.
2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.

However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue: 
- Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag).
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. 

Some common mistakes are as such: 
- Having block-level elements within `<p>` tag
- Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation). 

<box type="success" seamless>

If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
Comment thread
wxwxwxwx9 marked this conversation as resolved.

</box>

Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
Update Developer Guide on SSR based on feedback by wxwxwxwx9 · Pull Request #1573 · MarkBind/markbind · GitHub
Skip to content
Update Developer Guide on SSR based on feedback#1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ang-zeyu
merged 6 commits into

from

Jun 16, 2021
 Merged


Update Developer Guide on SSR based on feedback
#1573
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cc2cfb3

Update SSR Guide


wxwxwxwx9 Jun 5, 2021
913485d

Add full stop


wxwxwxwx9 Jun 5, 2021
ee47c97

Update according to review


wxwxwxwx9 Jun 5, 2021
c103475

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
b943064

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
e5f5c3a

Update serverSideRendering.md


wxwxwxwx9 Jun 13, 2021

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


34 changes: 27 additions & 7 deletions
docs/devGuide/design/serverSideRendering.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,11 @@

<div class="lead">

MarkBind makes use of Server-side Rendering (SSR) for its pages. 
MarkBind uses Server-side Rendering (SSR) for its pages. 

To ensure SSR works properly, there are certain rules that developers should adhere to. 

This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind. 
This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind. 
</div>

## Pre-requisite Knowledge
Expand All@@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue:
- Are there any differences between compiling Vue on client-side versus server-side?
- What is the difference between compiling and rendering?

### MarkBind's Packages
<box type="info" header="##### Useful Resources to understand Vue better" seamless>

If there are any doubts regarding the questions above, here are some good resources to refer to:

- [Vue Official Documentation](https://vuejs.org/v2/guide)
- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU)
</box>

### Understanding MarkBind's Packages

There are four packages in MarkBind's codebase:
1. cli
Expand All@@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance

SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML.

During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.
During the hydration process, Vue essentially compares your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.

This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. 

<box type="warning" header="#### Using production build" seamless>

In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option).
</box>

## Penalties of Hydration Issue

When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards).
Expand All@@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c
Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". 

It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things:
1) the state data are the same between client-side and server-side.
1) the initial state is the same between client-side and server-side.
2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.

However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue: 
- Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag).
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. 

Some common mistakes are as such: 
- Having block-level elements within `<p>` tag
- Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation). 

<box type="success" seamless>

If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
Comment thread
wxwxwxwx9 marked this conversation as resolved.

</box>

Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Update Developer Guide on SSR based on feedback by wxwxwxwx9 · Pull Request #1573 · MarkBind/markbind · GitHub
Skip to content
Update Developer Guide on SSR based on feedback#1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ang-zeyu
merged 6 commits into

from

Jun 16, 2021
 Merged


Update Developer Guide on SSR based on feedback
#1573
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cc2cfb3

Update SSR Guide


wxwxwxwx9 Jun 5, 2021
913485d

Add full stop


wxwxwxwx9 Jun 5, 2021
ee47c97

Update according to review


wxwxwxwx9 Jun 5, 2021
c103475

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
b943064

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
e5f5c3a

Update serverSideRendering.md


wxwxwxwx9 Jun 13, 2021

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


34 changes: 27 additions & 7 deletions
docs/devGuide/design/serverSideRendering.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,11 @@

<div class="lead">

MarkBind makes use of Server-side Rendering (SSR) for its pages. 
MarkBind uses Server-side Rendering (SSR) for its pages. 

To ensure SSR works properly, there are certain rules that developers should adhere to. 

This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind. 
This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind. 
</div>

## Pre-requisite Knowledge
Expand All@@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue:
- Are there any differences between compiling Vue on client-side versus server-side?
- What is the difference between compiling and rendering?

### MarkBind's Packages
<box type="info" header="##### Useful Resources to understand Vue better" seamless>

If there are any doubts regarding the questions above, here are some good resources to refer to:

- [Vue Official Documentation](https://vuejs.org/v2/guide)
- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU)
</box>

### Understanding MarkBind's Packages

There are four packages in MarkBind's codebase:
1. cli
Expand All@@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance

SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML.

During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.
During the hydration process, Vue essentially compares your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.

This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. 

<box type="warning" header="#### Using production build" seamless>

In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option).
</box>

## Penalties of Hydration Issue

When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards).
Expand All@@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c
Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". 

It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things:
1) the state data are the same between client-side and server-side.
1) the initial state is the same between client-side and server-side.
2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.

However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue: 
- Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag).
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. 

Some common mistakes are as such: 
- Having block-level elements within `<p>` tag
- Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation). 

<box type="success" seamless>

If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
Comment thread
wxwxwxwx9 marked this conversation as resolved.

</box>

Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Update Developer Guide on SSR based on feedback by wxwxwxwx9 · Pull Request #1573 · MarkBind/markbind · GitHub
Skip to content
Update Developer Guide on SSR based on feedback#1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ang-zeyu
merged 6 commits into

from

Jun 16, 2021
 Merged


Update Developer Guide on SSR based on feedback
#1573
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cc2cfb3

Update SSR Guide


wxwxwxwx9 Jun 5, 2021
913485d

Add full stop


wxwxwxwx9 Jun 5, 2021
ee47c97

Update according to review


wxwxwxwx9 Jun 5, 2021
c103475

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
b943064

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
e5f5c3a

Update serverSideRendering.md


wxwxwxwx9 Jun 13, 2021

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


34 changes: 27 additions & 7 deletions
docs/devGuide/design/serverSideRendering.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,11 @@

<div class="lead">

MarkBind makes use of Server-side Rendering (SSR) for its pages. 
MarkBind uses Server-side Rendering (SSR) for its pages. 

To ensure SSR works properly, there are certain rules that developers should adhere to. 

This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind. 
This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind. 
</div>

## Pre-requisite Knowledge
Expand All@@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue:
- Are there any differences between compiling Vue on client-side versus server-side?
- What is the difference between compiling and rendering?

### MarkBind's Packages
<box type="info" header="##### Useful Resources to understand Vue better" seamless>

If there are any doubts regarding the questions above, here are some good resources to refer to:

- [Vue Official Documentation](https://vuejs.org/v2/guide)
- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU)
</box>

### Understanding MarkBind's Packages

There are four packages in MarkBind's codebase:
1. cli
Expand All@@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance

SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML.

During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.
During the hydration process, Vue essentially compares your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.

This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. 

<box type="warning" header="#### Using production build" seamless>

In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option).
</box>

## Penalties of Hydration Issue

When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards).
Expand All@@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c
Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". 

It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things:
1) the state data are the same between client-side and server-side.
1) the initial state is the same between client-side and server-side.
2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.

However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue: 
- Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag).
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. 

Some common mistakes are as such: 
- Having block-level elements within `<p>` tag
- Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation). 

<box type="success" seamless>

If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
Comment thread
wxwxwxwx9 marked this conversation as resolved.

</box>

Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
Update Developer Guide on SSR based on feedback by wxwxwxwx9 · Pull Request #1573 · MarkBind/markbind · GitHub
Skip to content
Update Developer Guide on SSR based on feedback#1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ang-zeyu
merged 6 commits into

from

Jun 16, 2021
 Merged


Update Developer Guide on SSR based on feedback
#1573
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cc2cfb3

Update SSR Guide


wxwxwxwx9 Jun 5, 2021
913485d

Add full stop


wxwxwxwx9 Jun 5, 2021
ee47c97

Update according to review


wxwxwxwx9 Jun 5, 2021
c103475

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
b943064

Update serverSideRendering.md


wxwxwxwx9 Jun 6, 2021
e5f5c3a

Update serverSideRendering.md


wxwxwxwx9 Jun 13, 2021

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


34 changes: 27 additions & 7 deletions
docs/devGuide/design/serverSideRendering.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,11 @@

<div class="lead">

MarkBind makes use of Server-side Rendering (SSR) for its pages. 
MarkBind uses Server-side Rendering (SSR) for its pages. 

To ensure SSR works properly, there are certain rules that developers should adhere to. 

This page will describe SSR in general and elaborate on the things that developers should take note of when contributing to MarkBind. 
This page will describe SSR in general and elaborate on the caveats that developers should take note of when contributing to MarkBind. 
</div>

## Pre-requisite Knowledge
Expand All@@ -33,7 +33,15 @@ Here is a short list of questions to check your understanding of Vue:
- Are there any differences between compiling Vue on client-side versus server-side?
- What is the difference between compiling and rendering?

### MarkBind's Packages
<box type="info" header="##### Useful Resources to understand Vue better" seamless>

If there are any doubts regarding the questions above, here are some good resources to refer to:

- [Vue Official Documentation](https://vuejs.org/v2/guide)
- [Evan You - Inside Vue Components - Laracon EU 2017](https://www.youtube.com/watch?v=wZN_FtZRYC8&ab_channel=LaraconEU)
</box>

### Understanding MarkBind's Packages

There are four packages in MarkBind's codebase:
1. cli
Expand All@@ -53,10 +61,15 @@ The main motivation that we had for introducing SSR into MarkBind is to enhance

SSR and Client-side Hydration are 2 concepts that go hand-in-hand. Essentially, once we produce the static HTML via SSR and send it over to the client-side, Vue on the client-side will execute what is known as Client-side Hydration on the static HTML.

During the hydration process, Vue essentially `diff` your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.
During the hydration process, Vue essentially compares your SSR HTML markup against the virtual DOM generated by the render function on the client-side. If any difference is found, meaning that the application that we have on the client-side (the virtual DOM tree) differs from the SSR HTML mark-up that we send to the client, Vue will reject the SSR HTML output, bail Client-side Hydration, and execute full CSR.

This is known as "Hydration Issue" and it is one of the main challenges you will face with SSR in MarkBind. 

<box type="warning" header="#### Using production build" seamless>

In production build, Vue does not perform hydration check. Any errors resulting from hydration will trigger full CSR without warning. MarkBind **uses the development build by default** when you serve it in development mode (`-d` option).
</box>

## Penalties of Hydration Issue

When hydration fails, on top of the wasted time and effort in executing SSR, we will also incur the additional time penalty of executing Client-side Hydration (where CSR will follow afterwards).
Expand All@@ -70,11 +83,18 @@ Supposedly, hydration issues typically occurs due to minor differences between c
Conceptually, to prevent hydration issue, what we should always strive to achieve is a "universal application". 

It is not difficult to achieve a "universal application" per-se because we merely have to ensure two things:
1) the state data are the same between client-side and server-side.
1) the initial state is the same between client-side and server-side.
2) after compiling and rendering the Vue page application, the SSR HTML mark-up is not modified.

However, beyond achieving a "universal application", there are also some more specific rules that we should adhere to, so that we do not run into hydration issue: 
- Do not violate HTML spec as much as possible (e.g. having block-level elements within `<p>` tag).
Beyond achieving a "universal application", note that the HTML specifications should also be adhered to. 

Some common mistakes are as such: 
- Having block-level elements within `<p>` tag
- Having unknown HTML elements within our Vue application during compilation/rendering (though this can be easily resolved by adding `v-pre` to the unknown element, so that Vue will ignore that element during compilation). 

<box type="success" seamless>

If you are unsure what elements are allowed within other elements, or what constitutes invalid HTML in general, a good resource to reference would be the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span).
Comment thread
wxwxwxwx9 marked this conversation as resolved.

</box>

Note that the list only included the common causes of hydration issue that MarkBind developers have ran into. There may be other causes of hydration issue that are not listed here (although unlikely).