From d7ff7b0abd8154e3cdb826484c2d9c6372074ad1 Mon Sep 17 00:00:00 2001 From: Craig Beck Date: Thu, 30 May 2024 13:23:10 -0700 Subject: [PATCH 1/5] Add troubleshooting guide --- docs/README.md | 4 +-- docs/troubleshooting.md | 68 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 docs/troubleshooting.md diff --git a/docs/README.md b/docs/README.md index b6ca50b6..301d6aec 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,7 +11,7 @@ Jekyll has a dev server, which will auto-build the docs upon any changes to the Setup: ``` -cd derby-docs && bundle install +cd docs && bundle install ``` Run the dev server: @@ -27,7 +27,7 @@ The site is viewable at `http://localhost:4000/derby/`. One-time container creation: ``` -docker run --name derby-docs-ruby -v "$(pwd)/docs:/derby-docs" -p 127.0.0.1:4000:4000 ruby:2.7 bash -c 'cd derby-docs && bundle install && bundle exec jekyll serve -H 0.0.0.0 -P 4000 --trace' +docker run --name derby-docs-ruby -v "$(pwd)/docs:/docs" -p 127.0.0.1:4000:4000 ruby:2.7 bash -c 'cd docs && bundle install && bundle exec jekyll serve -H 0.0.0.0 -P 4000 --trace' ``` Subsequently, to run the dev server: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..88f5fede --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,68 @@ +--- +layout: default +title: Troubleshooting +--- + +# Troubleshooting + +This guide covers common issues that you may run into as you use Derby. Feel free to contribute your own troubleshooting experience! :) + +## Attaching bindings failed, because HTML structure does not match client rendering + +When the page is loaded on the browser, the following error might be thrown in the console: + +``` +Attaching bindings failed, because HTML structure does not match client rendering +``` + +... along with the problematic view that is causing this issue. It can be tricky to understand what caused the error if you touched a bunch of files at the same time (JS, HTML, CSS) and being unsure what caused the problem in the first place. Turns out, it's always about the HTML structure. + +When the page is rendered server side and is sent down to the client, Derby it will ensure that both HTML structures are exactly the same before attaching. If they don't match that is usually because the browser's parser attempts to gracefully handle invalid HTML that you may have introduced by mistake. For example, the following syntax is valid XML syntax but invalid HTML: + +```jinja +

+

+
+

+``` + +Browsers will effectively turn this into: + +```jinja +

+
+``` + +... according to the HTML rules set by W3: + +> The P element represents a paragraph. It cannot contain block-level elements (including P itself). We discourage authors from using empty P elements. User agents should ignore empty P elements. + +source: https://www.w3.org/TR/html401/struct/text.html#edef-P + +The same goes for HTML tables where: + +```jinja + + +
+``` + +... may be rendered by a browser as: + +```jinja + + + + + + +
+``` + +There are many other ways where parsers will try to "fix" invalid HTML and cause Derby to fail attaching. + +Here are a few common possibilities: +* invalid HTML (as illustrated above) +* sorting lists on in `init()` might cause the output to be non-deterministic (like alphabetizing / capitalization). Basically a data "bug" would end-up generated different HTML. +* putting links in links, which has undefined behavior in HTML +* inserting a conditional `
` such as `{{if thisIsTrue}}
stuff
{{/if}}` without restarting the server \ No newline at end of file From add208b69e117ae18f5509eda2fe164050d22814 Mon Sep 17 00:00:00 2001 From: Craig Beck Date: Thu, 30 May 2024 14:17:57 -0700 Subject: [PATCH 2/5] Update with metadata and preferred syntax highlighting --- docs/guides/troubleshooting.md | 13 +++++-- docs/troubleshooting.md | 68 ---------------------------------- 2 files changed, 9 insertions(+), 72 deletions(-) delete mode 100644 docs/troubleshooting.md diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index df35e140..b133bb6a 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -1,3 +1,8 @@ +---- +-layout: default +-title: Troubleshooting +---- + # Troubleshooting This guide covers common issues that you may run into as you use Derby. Feel free to contribute your own troubleshooting experience! :) @@ -14,7 +19,7 @@ Attaching bindings failed, because HTML structure does not match client renderin When the page is rendered server side and is sent down to the client, Derby it will ensure that both HTML structures are exactly the same before attaching. If they don't match that is usually because the browser's parser attempts to gracefully handle invalid HTML that you may have introduced by mistake. For example, the following syntax is valid XML syntax but invalid HTML: -```html +```jinja

@@ -23,7 +28,7 @@ When the page is rendered server side and is sent down to the client, Derby it w Browsers will effectively turn this into: -```html +```jinja

``` @@ -36,7 +41,7 @@ source: https://www.w3.org/TR/html401/struct/text.html#edef-P The same goes for HTML tables where: -```html +```jinja
@@ -44,7 +49,7 @@ The same goes for HTML tables where: ... may be rendered by a browser as: -```html +```jinja diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index 88f5fede..00000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -layout: default -title: Troubleshooting ---- - -# Troubleshooting - -This guide covers common issues that you may run into as you use Derby. Feel free to contribute your own troubleshooting experience! :) - -## Attaching bindings failed, because HTML structure does not match client rendering - -When the page is loaded on the browser, the following error might be thrown in the console: - -``` -Attaching bindings failed, because HTML structure does not match client rendering -``` - -... along with the problematic view that is causing this issue. It can be tricky to understand what caused the error if you touched a bunch of files at the same time (JS, HTML, CSS) and being unsure what caused the problem in the first place. Turns out, it's always about the HTML structure. - -When the page is rendered server side and is sent down to the client, Derby it will ensure that both HTML structures are exactly the same before attaching. If they don't match that is usually because the browser's parser attempts to gracefully handle invalid HTML that you may have introduced by mistake. For example, the following syntax is valid XML syntax but invalid HTML: - -```jinja -

-

-
-

-``` - -Browsers will effectively turn this into: - -```jinja -

-
-``` - -... according to the HTML rules set by W3: - -> The P element represents a paragraph. It cannot contain block-level elements (including P itself). We discourage authors from using empty P elements. User agents should ignore empty P elements. - -source: https://www.w3.org/TR/html401/struct/text.html#edef-P - -The same goes for HTML tables where: - -```jinja -
- -
-``` - -... may be rendered by a browser as: - -```jinja - - - - - - -
-``` - -There are many other ways where parsers will try to "fix" invalid HTML and cause Derby to fail attaching. - -Here are a few common possibilities: -* invalid HTML (as illustrated above) -* sorting lists on in `init()` might cause the output to be non-deterministic (like alphabetizing / capitalization). Basically a data "bug" would end-up generated different HTML. -* putting links in links, which has undefined behavior in HTML -* inserting a conditional `
` such as `{{if thisIsTrue}}
stuff
{{/if}}` without restarting the server \ No newline at end of file From ee5b69e5a54a1eb36c7f3a6816676823ab595251 Mon Sep 17 00:00:00 2001 From: Craig Beck Date: Thu, 30 May 2024 14:39:04 -0700 Subject: [PATCH 3/5] Integrate troubleshooting guide into doc site nav --- docs/guides.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 docs/guides.md diff --git a/docs/guides.md b/docs/guides.md new file mode 100644 index 00000000..8a559b1b --- /dev/null +++ b/docs/guides.md @@ -0,0 +1,5 @@ +--- +layout: default +title: Guides +has_children: true +--- From 1e7aeaa5475122676f5091ca177249d5cd357f3f Mon Sep 17 00:00:00 2001 From: Craig Beck Date: Thu, 30 May 2024 16:29:48 -0700 Subject: [PATCH 4/5] Fix frontmatter seperator; only three hyphens four just too much to handle --- docs/guides/troubleshooting.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index b133bb6a..e5e4b66b 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -1,7 +1,8 @@ ----- --layout: default --title: Troubleshooting ----- +--- +layout: default +title: Troubleshooting +parent: Guides +--- # Troubleshooting From 2605fac48a6cf6d0e20a2a708df546a1fbce6401 Mon Sep 17 00:00:00 2001 From: Craig Beck Date: Thu, 30 May 2024 16:31:53 -0700 Subject: [PATCH 5/5] Use derby-docs directory inside docker container --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 301d6aec..4364ffd9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -27,7 +27,7 @@ The site is viewable at `http://localhost:4000/derby/`. One-time container creation: ``` -docker run --name derby-docs-ruby -v "$(pwd)/docs:/docs" -p 127.0.0.1:4000:4000 ruby:2.7 bash -c 'cd docs && bundle install && bundle exec jekyll serve -H 0.0.0.0 -P 4000 --trace' +docker run --name derby-docs-ruby -v "$(pwd)/docs:/derby-docs" -p 127.0.0.1:4000:4000 ruby:2.7 bash -c 'cd derby-docs && bundle install && bundle exec jekyll serve -H 0.0.0.0 -P 4000 --trace' ``` Subsequently, to run the dev server: