diff --git a/cspell.json b/cspell.json
index 2503fa67a..a9c5043f0 100644
--- a/cspell.json
+++ b/cspell.json
@@ -71,6 +71,7 @@
"haspopup",
"heroicons",
"hexa",
+ "Hotwire",
"Iconoir",
"Iframes",
"iife",
@@ -95,6 +96,7 @@
"Menlo",
"menuitemcheckbox",
"menuitemradio",
+ "metaframeworks",
"middlewares",
"minlength",
"monospace",
@@ -139,6 +141,7 @@
"scroller",
"Segoe",
"semibold",
+ "shadowrootmode",
"Shortcode",
"Shortcodes",
"sitedir",
diff --git a/docs/docs/experimental/ssr.md b/docs/docs/experimental/ssr.md
index ec3d41135..c9aa68d67 100644
--- a/docs/docs/experimental/ssr.md
+++ b/docs/docs/experimental/ssr.md
@@ -1,23 +1,25 @@
---
title: Server Side Rendering
description: A document on how to get started with SSR in Web Awesome.
-layout: page
+layout: page-outline
---
-## Caveats
+Server Side Rendering ("SSR") means your webpage is rendered on the server before being sent to the user's browser. This provides a fully formed HTML page right from the start, which is great for SEO and initial load times. Once the page is rendered, JavaScript kicks in to "hydrate" the components which makes them interactive. The Web platform supports this through a feature called [Declarative Shadow DOM](https://web.dev/articles/declarative-shadow-dom).
-SSR in Web Awesome is to be considered experimental. There are bugs and timing issues. There are things to iron out. Please bear with us. Part of the experimental status comes from Lit SSR being experimental, and all of our components originally being designed as client only.
+:::warning
+SSR in Web Awesome is experimental! There are some known bugs and timing issues. Part of the experimental status comes from Lit's SSR package also being experimental.
+:::
-## Adding hydration to the Frontend
+## Enable Hydration
-If you're using the `webawesome.loader.js` file which automatically loads , make sure to change it to `webawesome.ssr-loader.js`
+If you're using the `webawesome.loader.js` file which automatically loads, make sure to change it to `webawesome.ssr-loader.js`.
```diff
-
+
```
-If you're using a bundler:
+If you're using a bundler, make sure it comes _before_ any components are imported.
```js
// Make sure this import is first.
@@ -27,15 +29,11 @@ import "webawesome/dist/components/button/button.js"
import "webawesome/dist/components/input/input.js"
```
-## Server rendering
+## Enable Server Rendering
-SSR on your backend is largely dependent on what backend you're using.
+How to implement SSR on the backend is largely dependent on what stack you're using. For docs on how to hook up your backend, refer to [this document from Lit](https://lit.dev/docs/ssr/server-usage/).
-For docs on how to hook up your backend, checkout this document from Lit:
-
-
-
-For example, here's roughly what the 11ty integration looks like:
+For example, here's what the [11ty](https://www.11ty.dev/) integration looks like using [Lit's 11ty plugin](https://www.npmjs.com/package/@lit-labs/eleventy-plugin-lit).
```js
// eleventy.config.js
@@ -51,31 +49,39 @@ import litPlugin from '@lit-labs/eleventy-plugin-lit';
});
```
-## Hydration
+:::info
+As SSR becomes more stable, we'll work to add more instructions for various frameworks and metaframeworks.
+:::
-All Web Awesome components that get SSR'ed will have `did-ssr=""` on them.
+## Helpful Tips
-For example: ``
+### The `did-ssr` Attribute
+
+All Web Awesome components that get rendered for SSR will receive the `did-ssr` attribute.
+
+```html
+
+```
This can help if you need some styling prior to the element connecting.
-## Timing issues
+### Timing Issues
-Before setting any properties on your frontend, it is important to first wait for the element to be defined, and then wait for its update to complete.
+Before setting any properties on your frontend, it is important to first wait for the element to be defined and then wait for its first update to complete.
```js
-const rating = document.querySelector("wa-rating")
+const rating = document.querySelector('wa-rating');
-// If we dont want for the component to be defined, and for the initial hydration to finish, we will get a hydration error from Lit.
-await customElements.whenDefined("wa-rating")
-await rating.updateComplete
+// If we don't wait for the component to be defined the initial hydration, we will get a hydration error from Lit!
+await customElements.whenDefined('wa-rating');
+await rating.updateComplete;
rating.getSymbol = () => '';
```
-## Usage with Turbo
+### Usage with Turbo
-Turbo, the Hotwire library, has an issue with SSR + declarative shadow dom. To fix this, you can add the following.
+The Hotwire library [Turbo](https://github.com/hotwired/turbo) has an issue with SSR + declarative shadow DOM. To fix this, you can add the following to every page that runs Turbo.
```js
function fixDeclarativeShadowDOM(e) {
@@ -96,16 +102,18 @@ function fixDeclarativeShadowDOM(e) {
})(newElement);
}
-// Fixes an issue with DSD keeping the `` elements hanging around in the lightdom.
+// Fixes an issue with DSD keeping the `` elements hanging around in the light DOM.
// https://github.com/hotwired/turbo/issues/1292
['turbo:before-render', 'turbo:before-stream-render', 'turbo:before-frame-render'].forEach(eventName => {
document.addEventListener(eventName, fixDeclarativeShadowDOM);
});
```
-## Additional TODOs
+## Known Issues
-- [ ] - `@shoelace-style/localize` (our localization library) has no way to set a language currently so it always falls back to `en`.
-- [ ] - `` has no fallback if there's no JS besides a blank `