From 0732b99560d2544cae245ec28723f0be757f50be Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Mon, 6 Jun 2022 21:24:47 -0400
Subject: [PATCH 01/10] improve readability of header navigation links

---
 docs/components/navigation.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/components/navigation.js b/docs/components/navigation.js
index aae7936c..ba89e729 100644
--- a/docs/components/navigation.js
+++ b/docs/components/navigation.js
@@ -11,7 +11,7 @@ template.innerHTML = `
 
     nav ul li {
       float: left;
-      width: 33%;
+      width: 33.3%;
       text-align: center;
     }
 
@@ -20,6 +20,7 @@ template.innerHTML = `
       color: #efefef;
       min-width: 48px;
       min-height: 48px;
+      font-size: 2.5rem;
     }
   </style>
 

From 2d40e71776a0712ee79aeb8614d155997d769e56 Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Mon, 6 Jun 2022 21:25:31 -0400
Subject: [PATCH 02/10] add ToC for docs page

---
 build.js           |   6 +
 docs/pages/docs.md |   2 +
 package-lock.json  | 287 ++++++++++++++++++++++++++++++++++++++++++++-
 package.json       |   5 +-
 4 files changed, 297 insertions(+), 3 deletions(-)

diff --git a/build.js b/build.js
index 96bacb57..3014c1a0 100644
--- a/build.js
+++ b/build.js
@@ -1,9 +1,12 @@
 import fs from 'node:fs/promises';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 import rehypePrism from '@mapbox/rehype-prism';
+import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
 import rehypeRaw from 'rehype-raw';
 import remarkParse from 'remark-parse';
 import remarkRehype from 'remark-rehype';
+import remarkToc from 'remark-toc';
 import { unified } from 'unified';
 
 import { renderToString } from './src/wcc.js';
@@ -32,8 +35,11 @@ async function init() {
     const markdown = await fs.readFile(new URL(pageLocation, import.meta.url), 'utf-8');
     let content = (await unified()
       .use(remarkParse)
+      .use(remarkToc, { tight: true })
       .use(remarkRehype, { allowDangerousHtml: true })
+      .use(rehypeSlug)
       .use(rehypeRaw)
+      .use(rehypeAutolinkHeadings)
       .use(rehypePrism)
       .use(rehypeStringify)
       .process(markdown)).value;
diff --git a/docs/pages/docs.md b/docs/pages/docs.md
index be7cc787..9fdfadd6 100644
--- a/docs/pages/docs.md
+++ b/docs/pages/docs.md
@@ -1,5 +1,7 @@
 # Documentation
 
+## Table of contents
+
 ## API
 
 ### renderToString
diff --git a/package-lock.json b/package-lock.json
index 1d4e89e8..6f421422 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "wc-compiler",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "wc-compiler",
-      "version": "0.1.0",
+      "version": "0.2.1",
       "license": "MIT",
       "dependencies": {
         "acorn": "^8.7.0",
@@ -24,10 +24,13 @@
         "mocha": "^9.2.2",
         "nodemon": "^2.0.15",
         "prismjs": "^1.28.0",
+        "rehype-autolink-headings": "^6.1.1",
         "rehype-raw": "^6.1.1",
+        "rehype-slug": "^5.0.1",
         "rehype-stringify": "^9.0.3",
         "remark-parse": "^10.0.1",
         "remark-rehype": "^10.1.0",
+        "remark-toc": "^8.0.1",
         "simple.css": "^0.1.3",
         "unified": "^10.1.2"
       },
@@ -224,6 +227,18 @@
         "@types/ms": "*"
       }
     },
+    "node_modules/@types/extend": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/@types/extend/-/extend-3.0.1.tgz",
+      "integrity": "sha512-R1g/VyKFFI2HLC1QGAeTtCBWCo6n75l41OnsVYNbmKG+kempOESaodf6BeJyUM3Q0rKa/NQcTHbB2+66lNnxLw==",
+      "dev": true
+    },
+    "node_modules/@types/github-slugger": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/@types/github-slugger/-/github-slugger-1.3.0.tgz",
+      "integrity": "sha512-J/rMZa7RqiH/rT29TEVZO4nBoDP9XJOjnbbIofg7GQKs4JIduEO3WLpte+6WeUz/TcrXKlY+bM7FYrp8yFB+3g==",
+      "dev": true
+    },
     "node_modules/@types/hast": {
       "version": "2.3.4",
       "resolved": "https://registry.npmjs.org/@types/hast/-/hast-2.3.4.tgz",
@@ -2247,6 +2262,12 @@
         "node": ">=0.8"
       }
     },
+    "node_modules/github-slugger": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-1.4.0.tgz",
+      "integrity": "sha512-w0dzqw/nt51xMVmlaV1+JRzN+oCa1KfcgGEWhxUG16wbdA+Xnt/yoFO8Z8x/V82ZcZ0wy6ln9QDup5avbhiDhQ==",
+      "dev": true
+    },
     "node_modules/glob": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
@@ -2518,6 +2539,29 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/hast-util-has-property": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-has-property/-/hast-util-has-property-2.0.0.tgz",
+      "integrity": "sha512-4Qf++8o5v14us4Muv3HRj+Er6wTNGA/N9uCaZMty4JWvyFKLdhULrv4KE1b65AthsSO9TXSZnjuxS8ecIyhb0w==",
+      "dev": true,
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-heading-rank": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/hast-util-heading-rank/-/hast-util-heading-rank-2.1.0.tgz",
+      "integrity": "sha512-w+Rw20Q/iWp2Bcnr6uTrYU6/ftZLbHKhvc8nM26VIWpDqDMlku2iXUVTeOlsdoih/UKQhY7PHQ+vZ0Aqq8bxtQ==",
+      "dev": true,
+      "dependencies": {
+        "@types/hast": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/hast-util-is-element": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/hast-util-is-element/-/hast-util-is-element-2.1.2.tgz",
@@ -4464,6 +4508,55 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/mdast-util-toc": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-toc/-/mdast-util-toc-6.1.0.tgz",
+      "integrity": "sha512-0PuqZELXZl4ms1sF7Lqigrqik4Ll3UhbI+jdTrfw7pZ9QPawgl7LD4GQ8MkU7bT/EwiVqChNTbifa2jLLKo76A==",
+      "dev": true,
+      "dependencies": {
+        "@types/extend": "^3.0.0",
+        "@types/github-slugger": "^1.0.0",
+        "@types/mdast": "^3.0.0",
+        "extend": "^3.0.0",
+        "github-slugger": "^1.0.0",
+        "mdast-util-to-string": "^3.1.0",
+        "unist-util-is": "^5.0.0",
+        "unist-util-visit": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-toc/node_modules/unist-util-visit": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-3.1.0.tgz",
+      "integrity": "sha512-Szoh+R/Ll68QWAyQyZZpQzZQm2UPbxibDvaY8Xc9SUtYgPsDzx5AWSk++UUt2hJuow8mvwR+rG+LQLw+KsuAKA==",
+      "dev": true,
+      "dependencies": {
+        "@types/unist": "^2.0.0",
+        "unist-util-is": "^5.0.0",
+        "unist-util-visit-parents": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-toc/node_modules/unist-util-visit-parents": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-4.1.1.tgz",
+      "integrity": "sha512-1xAFJXAKpnnJl8G7K5KgU7FY55y3GcLIXqkzUj5QF/QVP7biUm0K0O2oqVkYsdjzJKifYeWn9+o6piAK2hGSHw==",
+      "dev": true,
+      "dependencies": {
+        "@types/unist": "^2.0.0",
+        "unist-util-is": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/mdurl": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz",
@@ -6237,6 +6330,25 @@
         "node": ">=8"
       }
     },
+    "node_modules/rehype-autolink-headings": {
+      "version": "6.1.1",
+      "resolved": "https://registry.npmjs.org/rehype-autolink-headings/-/rehype-autolink-headings-6.1.1.tgz",
+      "integrity": "sha512-NMYzZIsHM3sA14nC5rAFuUPIOfg+DFmf9EY1YMhaNlB7+3kK/ZlE6kqPfuxr1tsJ1XWkTrMtMoyHosU70d35mA==",
+      "dev": true,
+      "dependencies": {
+        "@types/hast": "^2.0.0",
+        "extend": "^3.0.0",
+        "hast-util-has-property": "^2.0.0",
+        "hast-util-heading-rank": "^2.0.0",
+        "hast-util-is-element": "^2.0.0",
+        "unified": "^10.0.0",
+        "unist-util-visit": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/rehype-raw": {
       "version": "6.1.1",
       "resolved": "https://registry.npmjs.org/rehype-raw/-/rehype-raw-6.1.1.tgz",
@@ -6253,6 +6365,38 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/rehype-slug": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/rehype-slug/-/rehype-slug-5.0.1.tgz",
+      "integrity": "sha512-X5v3wV/meuOX9NFcGhJvUpEjIvQl2gDvjg3z40RVprYFt7q3th4qMmYLULiu3gXvbNX1ppx+oaa6JyY1W67pTA==",
+      "dev": true,
+      "dependencies": {
+        "@types/hast": "^2.0.0",
+        "github-slugger": "^1.1.1",
+        "hast-util-has-property": "^2.0.0",
+        "hast-util-heading-rank": "^2.0.0",
+        "hast-util-to-string": "^2.0.0",
+        "unified": "^10.0.0",
+        "unist-util-visit": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/rehype-slug/node_modules/hast-util-to-string": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-2.0.0.tgz",
+      "integrity": "sha512-02AQ3vLhuH3FisaMM+i/9sm4OXGSq1UhOOCpTLLQtHdL3tZt7qil69r8M8iDkZYyC0HCFylcYoP+8IO7ddta1A==",
+      "dev": true,
+      "dependencies": {
+        "@types/hast": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/rehype-stringify": {
       "version": "9.0.3",
       "resolved": "https://registry.npmjs.org/rehype-stringify/-/rehype-stringify-9.0.3.tgz",
@@ -6302,6 +6446,21 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/remark-toc": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/remark-toc/-/remark-toc-8.0.1.tgz",
+      "integrity": "sha512-7he2VOm/cy13zilnOTZcyAoyoolV26ULlon6XyCFU+vG54Z/LWJnwphj/xKIDLOt66QmJUgTyUvLVHi2aAElyg==",
+      "dev": true,
+      "dependencies": {
+        "@types/mdast": "^3.0.0",
+        "mdast-util-toc": "^6.0.0",
+        "unified": "^10.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/remote-origin-url": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/remote-origin-url/-/remote-origin-url-1.0.0.tgz",
@@ -7924,6 +8083,18 @@
         "@types/ms": "*"
       }
     },
+    "@types/extend": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/@types/extend/-/extend-3.0.1.tgz",
+      "integrity": "sha512-R1g/VyKFFI2HLC1QGAeTtCBWCo6n75l41OnsVYNbmKG+kempOESaodf6BeJyUM3Q0rKa/NQcTHbB2+66lNnxLw==",
+      "dev": true
+    },
+    "@types/github-slugger": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/@types/github-slugger/-/github-slugger-1.3.0.tgz",
+      "integrity": "sha512-J/rMZa7RqiH/rT29TEVZO4nBoDP9XJOjnbbIofg7GQKs4JIduEO3WLpte+6WeUz/TcrXKlY+bM7FYrp8yFB+3g==",
+      "dev": true
+    },
     "@types/hast": {
       "version": "2.3.4",
       "resolved": "https://registry.npmjs.org/@types/hast/-/hast-2.3.4.tgz",
@@ -9345,6 +9516,12 @@
         "remote-origin-url": "^1.0.0"
       }
     },
+    "github-slugger": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-1.4.0.tgz",
+      "integrity": "sha512-w0dzqw/nt51xMVmlaV1+JRzN+oCa1KfcgGEWhxUG16wbdA+Xnt/yoFO8Z8x/V82ZcZ0wy6ln9QDup5avbhiDhQ==",
+      "dev": true
+    },
     "glob": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz",
@@ -9533,6 +9710,21 @@
         }
       }
     },
+    "hast-util-has-property": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-has-property/-/hast-util-has-property-2.0.0.tgz",
+      "integrity": "sha512-4Qf++8o5v14us4Muv3HRj+Er6wTNGA/N9uCaZMty4JWvyFKLdhULrv4KE1b65AthsSO9TXSZnjuxS8ecIyhb0w==",
+      "dev": true
+    },
+    "hast-util-heading-rank": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/hast-util-heading-rank/-/hast-util-heading-rank-2.1.0.tgz",
+      "integrity": "sha512-w+Rw20Q/iWp2Bcnr6uTrYU6/ftZLbHKhvc8nM26VIWpDqDMlku2iXUVTeOlsdoih/UKQhY7PHQ+vZ0Aqq8bxtQ==",
+      "dev": true,
+      "requires": {
+        "@types/hast": "^2.0.0"
+      }
+    },
     "hast-util-is-element": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/hast-util-is-element/-/hast-util-is-element-2.1.2.tgz",
@@ -10906,6 +11098,45 @@
       "integrity": "sha512-n4Vypz/DZgwo0iMHLQL49dJzlp7YtAJP+N07MZHpjPf/5XJuHUWstviF4Mn2jEiR/GNmtnRRqnwsXExk3igfFA==",
       "dev": true
     },
+    "mdast-util-toc": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-toc/-/mdast-util-toc-6.1.0.tgz",
+      "integrity": "sha512-0PuqZELXZl4ms1sF7Lqigrqik4Ll3UhbI+jdTrfw7pZ9QPawgl7LD4GQ8MkU7bT/EwiVqChNTbifa2jLLKo76A==",
+      "dev": true,
+      "requires": {
+        "@types/extend": "^3.0.0",
+        "@types/github-slugger": "^1.0.0",
+        "@types/mdast": "^3.0.0",
+        "extend": "^3.0.0",
+        "github-slugger": "^1.0.0",
+        "mdast-util-to-string": "^3.1.0",
+        "unist-util-is": "^5.0.0",
+        "unist-util-visit": "^3.0.0"
+      },
+      "dependencies": {
+        "unist-util-visit": {
+          "version": "3.1.0",
+          "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-3.1.0.tgz",
+          "integrity": "sha512-Szoh+R/Ll68QWAyQyZZpQzZQm2UPbxibDvaY8Xc9SUtYgPsDzx5AWSk++UUt2hJuow8mvwR+rG+LQLw+KsuAKA==",
+          "dev": true,
+          "requires": {
+            "@types/unist": "^2.0.0",
+            "unist-util-is": "^5.0.0",
+            "unist-util-visit-parents": "^4.0.0"
+          }
+        },
+        "unist-util-visit-parents": {
+          "version": "4.1.1",
+          "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-4.1.1.tgz",
+          "integrity": "sha512-1xAFJXAKpnnJl8G7K5KgU7FY55y3GcLIXqkzUj5QF/QVP7biUm0K0O2oqVkYsdjzJKifYeWn9+o6piAK2hGSHw==",
+          "dev": true,
+          "requires": {
+            "@types/unist": "^2.0.0",
+            "unist-util-is": "^5.0.0"
+          }
+        }
+      }
+    },
     "mdurl": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz",
@@ -12056,6 +12287,21 @@
         "rc": "^1.2.8"
       }
     },
+    "rehype-autolink-headings": {
+      "version": "6.1.1",
+      "resolved": "https://registry.npmjs.org/rehype-autolink-headings/-/rehype-autolink-headings-6.1.1.tgz",
+      "integrity": "sha512-NMYzZIsHM3sA14nC5rAFuUPIOfg+DFmf9EY1YMhaNlB7+3kK/ZlE6kqPfuxr1tsJ1XWkTrMtMoyHosU70d35mA==",
+      "dev": true,
+      "requires": {
+        "@types/hast": "^2.0.0",
+        "extend": "^3.0.0",
+        "hast-util-has-property": "^2.0.0",
+        "hast-util-heading-rank": "^2.0.0",
+        "hast-util-is-element": "^2.0.0",
+        "unified": "^10.0.0",
+        "unist-util-visit": "^4.0.0"
+      }
+    },
     "rehype-raw": {
       "version": "6.1.1",
       "resolved": "https://registry.npmjs.org/rehype-raw/-/rehype-raw-6.1.1.tgz",
@@ -12067,6 +12313,32 @@
         "unified": "^10.0.0"
       }
     },
+    "rehype-slug": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/rehype-slug/-/rehype-slug-5.0.1.tgz",
+      "integrity": "sha512-X5v3wV/meuOX9NFcGhJvUpEjIvQl2gDvjg3z40RVprYFt7q3th4qMmYLULiu3gXvbNX1ppx+oaa6JyY1W67pTA==",
+      "dev": true,
+      "requires": {
+        "@types/hast": "^2.0.0",
+        "github-slugger": "^1.1.1",
+        "hast-util-has-property": "^2.0.0",
+        "hast-util-heading-rank": "^2.0.0",
+        "hast-util-to-string": "^2.0.0",
+        "unified": "^10.0.0",
+        "unist-util-visit": "^4.0.0"
+      },
+      "dependencies": {
+        "hast-util-to-string": {
+          "version": "2.0.0",
+          "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-2.0.0.tgz",
+          "integrity": "sha512-02AQ3vLhuH3FisaMM+i/9sm4OXGSq1UhOOCpTLLQtHdL3tZt7qil69r8M8iDkZYyC0HCFylcYoP+8IO7ddta1A==",
+          "dev": true,
+          "requires": {
+            "@types/hast": "^2.0.0"
+          }
+        }
+      }
+    },
     "rehype-stringify": {
       "version": "9.0.3",
       "resolved": "https://registry.npmjs.org/rehype-stringify/-/rehype-stringify-9.0.3.tgz",
@@ -12101,6 +12373,17 @@
         "unified": "^10.0.0"
       }
     },
+    "remark-toc": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/remark-toc/-/remark-toc-8.0.1.tgz",
+      "integrity": "sha512-7he2VOm/cy13zilnOTZcyAoyoolV26ULlon6XyCFU+vG54Z/LWJnwphj/xKIDLOt66QmJUgTyUvLVHi2aAElyg==",
+      "dev": true,
+      "requires": {
+        "@types/mdast": "^3.0.0",
+        "mdast-util-toc": "^6.0.0",
+        "unified": "^10.0.0"
+      }
+    },
     "remote-origin-url": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/remote-origin-url/-/remote-origin-url-1.0.0.tgz",
diff --git a/package.json b/package.json
index 5b8c42fb..255b732b 100644
--- a/package.json
+++ b/package.json
@@ -42,11 +42,14 @@
     "mocha": "^9.2.2",
     "nodemon": "^2.0.15",
     "prismjs": "^1.28.0",
-    "simple.css": "^0.1.3",
+    "rehype-autolink-headings": "^6.1.1",
     "rehype-raw": "^6.1.1",
+    "rehype-slug": "^5.0.1",
     "rehype-stringify": "^9.0.3",
     "remark-parse": "^10.0.1",
     "remark-rehype": "^10.1.0",
+    "remark-toc": "^8.0.1",
+    "simple.css": "^0.1.3",
     "unified": "^10.1.2"
   }
 }

From 029f7be09ab35f0144b93e7b507fa3010d0efe04 Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Tue, 7 Jun 2022 21:24:27 -0400
Subject: [PATCH 03/10] clean up README and decouple home page from README

---
 README.md           | 60 ++++++++++++-------------------
 build.js            | 10 +-----
 docs/pages/index.md | 88 +++++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 109 insertions(+), 49 deletions(-)

diff --git a/README.md b/README.md
index 1ecbc737..75f617f8 100644
--- a/README.md
+++ b/README.md
@@ -8,37 +8,9 @@
 
 **Web Components Compiler (WCC)** is a NodeJS package designed to make server-side rendering (SSR) of native Web Components easier.  It can render (within reason 😅) your Web Component into static HTML leveraging [Declarative Shadow DOM](https://web.dev/declarative-shadow-dom/).
 
-It is not a static site generator or framework.  It is focused on producing raw HTML from Web Components with the intent of being easily _integrated_ into a site generator or framework.
+## How It Works
 
-> _The original motivation for this project was to create a [purpose built, lighter weight alternative to puppeteer for SSR of native `HTMLElement` based Web Components](https://github.com/ProjectEvergreen/greenwood/issues/935) for the project [**Greenwood**](https://www.greenwoodjs.io/)._
-
-In addition, WCC hopes to provide a surface area to explore patterns around [streaming](https://github.com/ProjectEvergreen/wcc/issues/5) and serverless rendering, as well as acting as a test bed for the [Web Components Community Groups](https://github.com/webcomponents-cg) discussions around community protocols, like [hydration](https://github.com/ProjectEvergreen/wcc/issues/3).
-
-## Key Features
-
-1. Supports the following `HTMLElement` lifecycles and methods on the server side
-    - `constructor`
-    - `connectedCallback`
-    - `attachShadow`
-    - `innerHTML`
-    - `[get|set|has]Attribute`
-1. Recursive rendering of nested custom elements
-1. Optional Declarative Shadow DOM (for producing purely content driven static pages)
-1. Metadata and runtime hints to support progressive hydration and lazy loading strategies
-
-## Installation
-
-**wcc** can be installed from npm.
-
-```shell
-$ npm install wc-compiler --save-dev
-```
-
-## Usage
-
-WCC exposes a few utilities to render your Web Components.  Below is one example, with [full docs and more examples](https://merry-caramel-524e61.netlify.app/) available on the website.
-
-1. Given a custom element like so:
+1. Write a Web Component
     ```js
     const template = document.createElement('template');
 
@@ -68,17 +40,13 @@ WCC exposes a few utilities to render your Web Components.  Below is one example
 
     customElements.define('wcc-footer', Footer);
     ```
-
-1. Using NodeJS, create a file that imports `renderToString` and provide it the path to your web component
+1. Run it through the compiler
     ```js
     import { renderToString } from 'wc-compiler';
 
-    const { html } = await renderToString(new URL('./path/to/footer.js', import.meta.url));
-
-    console.debug({ html })
+    const { html } = await renderToString(new URL('./path/to/component.js', import.meta.url));
     ```
-
-1. You will get the following HTML output that can be used in conjunction with your preferred site framework or templating solution.
+1. Get HTML!
     ```html
     <wcc-footer>
       <template shadowroot="open">
@@ -96,5 +64,21 @@ WCC exposes a few utilities to render your Web Components.  Below is one example
     </wcc-footer>
     ```
 
+## Installation
+
+**WCC** can be installed from npm.
+
+```shell
+$ npm install wc-compiler --save-dev
+```
+
+## Documentation
+
+See our [website](https://merry-caramel-524e61.netlify.app/) for API docs and examples.
+
+
+## Motivation
+
+**WCC** is not a static site generator, framework or bundler.  It is focused on producing raw HTML from Web Components with the intent of being easily integrated into a site generator or framework, like [**Greenwood**](https://github.com/ProjectEvergreen/greenwood/), the original motivation for creating [this project](https://github.com/ProjectEvergreen/greenwood/issues/935).
 
-> _**Make sure to test in Chrome, or other Declarative Shadow DOM compatible browser, otherwise you will need to include the [DSD polyfill](https://web.dev/declarative-shadow-dom/#polyfill).**_
\ No newline at end of file
+In addition, **WCC** hopes to provide a surface area to explore patterns around [streaming](https://github.com/ProjectEvergreen/wcc/issues/5) and serverless rendering, as well as acting as a test bed for the [Web Components Community Groups](https://github.com/webcomponents-cg) discussions around community protocols, like [hydration](https://github.com/ProjectEvergreen/wcc/issues/3).
\ No newline at end of file
diff --git a/build.js b/build.js
index 3014c1a0..c4f51dd8 100644
--- a/build.js
+++ b/build.js
@@ -29,10 +29,7 @@ async function init() {
   await fs.copyFile(new URL('./docs/assets/favicon.ico', import.meta.url), new URL(`${distRoot}/favicon.ico`, import.meta.url));
 
   for (const page of pages) {
-    // for now, just repurposing the README for home page content
-    const isHomePage = page === 'index.md';
-    const pageLocation = isHomePage ? './README.md' : `${pagesRoot}/${page}`;
-    const markdown = await fs.readFile(new URL(pageLocation, import.meta.url), 'utf-8');
+    const markdown = await fs.readFile(new URL(`${pagesRoot}/${page}`, import.meta.url), 'utf-8');
     let content = (await unified()
       .use(remarkParse)
       .use(remarkToc, { tight: true })
@@ -44,11 +41,6 @@ async function init() {
       .use(rehypeStringify)
       .process(markdown)).value;
 
-    if (isHomePage) {
-      const contentFilter = content.substring(content.indexOf('<h1>wcc</h1>'), content.indexOf('<h2>Overview</h2>') + 17);
-      content = content.replace(contentFilter, '');
-    }
-
     const route = page.replace('.md', '');
     const outputPath = route === 'index' ? '' : `${route}/`;
 
diff --git a/docs/pages/index.md b/docs/pages/index.md
index 8917aafc..5e01c7c0 100644
--- a/docs/pages/index.md
+++ b/docs/pages/index.md
@@ -1,3 +1,87 @@
-# Home
+# Introduction
 
-This is just a placeholder for the contents of README.md.
\ No newline at end of file
+**Web Components Compiler (WCC)** is a NodeJS package designed to make server-side rendering (SSR) of native Web Components easier.  It can render (within reason 😅) your Web Component into static HTML leveraging [Declarative Shadow DOM](https://web.dev/declarative-shadow-dom/).
+
+## Installation
+
+**WCC** can be installed from npm.
+
+```shell
+$ npm install wc-compiler --save-dev
+```
+
+## Key Features
+
+1. Supports the following `HTMLElement` lifecycles and methods on the server side
+    - `constructor`
+    - `connectedCallback`
+    - `attachShadow`
+    - `innerHTML`
+    - `[get|set|has]Attribute`
+1. `<template>` / `DocumentFragment`
+1. Recursive rendering of nested custom elements
+1. Optional Declarative Shadow DOM (for producing purely content driven static pages)
+1. Metadata and runtime hints to support progressive hydration and lazy loading strategies
+
+## Usage
+
+**WCC** exposes a few utilities to render your Web Components.  See [our API docs](/docs) for all available features.
+
+1. Given a custom element like so:
+    ```js
+    const template = document.createElement('template');
+
+    template.innerHTML = `
+      <style>
+        .footer {
+          color: white;
+          background-color: #192a27;
+        }
+      </style>
+
+      <footer class="footer">
+        <h4>My Blog &copy; ${new Date().getFullYear()}</h4>
+      </footer>
+    `;
+
+    class Footer extends HTMLElement {
+      connectedCallback() {
+        if (!this.shadowRoot) {
+          this.attachShadow({ mode: 'open' });
+          this.shadowRoot.appendChild(template.content.cloneNode(true));
+        }
+      }
+    }
+
+    export default Footer;
+
+    customElements.define('wcc-footer', Footer);
+    ```
+
+1. Using NodeJS, create a file that imports `renderToString` and provide it the path to your web component
+    ```js
+    import { renderToString } from 'wc-compiler';
+
+    const { html } = await renderToString(new URL('./path/to/footer.js', import.meta.url));
+    ```
+
+1. You will get the following HTML output that can be used in conjunction with your preferred site framework or templating solution.
+    ```html
+    <wcc-footer>
+      <template shadowroot="open">
+        <style>
+          .footer {
+            color: white;
+            background-color: #192a27;
+          }
+        </style>
+
+        <footer class="footer">
+          <h4>My Blog &copy; 2022</h4>
+        </footer>
+      </template>
+    </wcc-footer>
+    ```
+
+
+> _**Make sure to test in Chrome, or other Declarative Shadow DOM compatible browser, otherwise you will need to include the [polyfill](https://web.dev/declarative-shadow-dom/#polyfill).**_
\ No newline at end of file

From 6238fc3bfda43d819a9d25c2e00e3a6ce96623c4 Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Tue, 7 Jun 2022 22:24:32 -0400
Subject: [PATCH 04/10] examples first draft

---
 docs/pages/examples.md | 263 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 262 insertions(+), 1 deletion(-)

diff --git a/docs/pages/examples.md b/docs/pages/examples.md
index aba64553..d2e72094 100644
--- a/docs/pages/examples.md
+++ b/docs/pages/examples.md
@@ -1,3 +1,264 @@
 # Examples
 
-Coming Soon!
\ No newline at end of file
+Below are some example of how is **WCC** being used right now.
+
+## Table of contents
+
+## Server Rendering (SSR)
+
+For the project [**Greenwood**](https://github.com/ProjectEvergreen/greenwood), **WCC** is being used to provide a _Next.js_ like experience by allowing users to author server-side route using native custom elements!
+
+```js
+import '../components/card/card.js';
+import fetch from 'node-fetch';
+
+export default class ArtistsPage extends HTMLElement {
+  async connectedCallback() {
+    if (!this.shadowRoot) {
+      const artists = await fetch('https://www.domain.com/api/artists').then(resp => resp.json());
+      const html = artists.map(artist => {
+        return `
+          <wc-card>
+            <h2 slot="title">${artist.name}</h2>
+            <img slot="image" src="${artist.imageUrl}" alt="${artist.name}"/>
+          </wc-card>
+        `;
+      }).join('');
+
+      this.attachShadow({ mode: 'open' });
+      this.innerHTML = html;
+    }
+  }
+
+  ...
+}
+```
+
+## Serverless and Edge Functions
+
+In the talk [_"Web Components at the Edge"_](https://sched.co/11loQ) for OpenJS World 2022, **WCC** was leveraged in both the AWS Lambda serverless functions and Netlify Edge functions demos.  See all the [code, slides and demos in GitHub](https://github.com/thescientist13/web-components-at-the-edge).
+
+
+In addition to entirely server render Web Components with client side hydration (see [here](/examples#progressive-hydration)), it also shows some clever ways to use **WCC** in more constrained environments, like an edge runtime.
+
+```js
+import '../../node_modules/wc-compiler/src/dom-shim.js';
+
+import Greeting from './components/greeting.js';
+
+export default async function (request, context) {
+  const countryCode = context.geo.country.code || 'UNKNOWN';
+  const countryName = context.geo.country.name || 'UNKNOWN';
+  const greeting = new Greeting(countryCode, countryName);
+
+  greeting.connectedCallback();
+
+  const response = new Response(`
+    <!DOCTYPE html>
+    <html lang="en">
+      <head>
+        ...
+      </head>
+      <body>
+        <wc-greeting>
+          ${greeting.getInnerHTML({ includeShadowRoots: true })}
+          <details slot="details">
+            <pre>
+              ${JSON.stringify(context.geo)}
+            </pre>
+          </details>
+        </wc-greeting>
+      </body>
+    </html>
+  `);
+
+  response.headers.set('content-type', 'text/html');
+
+  return response;
+}
+```
+
+## Static Sites (SSG)
+
+Using `innerHTML`, custom elements can be authored to not use Shadow DOM, which can be useful for a `Layout` or `App` component where that top level content specifically should _not_ be in a shadow root, e.g. `<template>` tag.  What's nice about **WCC** is that by using `innerHTML` or `attachShadow`, you can opt in a per component basis, like we do for [the **WCC** website](https://github.com/thescientist13/wcc/tree/master/docs), where the content is authored in markdown, but the header, navigation, footer are all custom elements rendered to static HTML.
+```js
+// index.js, aka a Layout component
+import './components/footer.js';
+import './components/header.js';
+
+class Home extends HTMLElement {
+
+  connectedCallback() {
+    this.innerHTML = `
+      <style>
+        :root {
+          --accent: #367588;
+        }
+
+        body {
+          display: flex;
+          flex-direction: column;
+        }
+
+        main {
+          max-width: 1200px;
+          margin: 20px auto;
+        }
+
+        a:visited {
+          color: var(--accent);
+        }
+      </style>
+
+      <wcc-header></wcc-header>
+
+      <main>
+        <slot name="content"></slot>
+      </main>
+
+      <wcc-footer></wcc-footer>
+    `;
+  }
+}
+
+export default Home;
+```
+
+## Progressive Hydration
+
+Using the `metadata` information from a custom element with the `hydrate=true` attribute, you can use use this metadata to use an IntersectionObserver to progressively load a custom element.  See it in [action here](https://wc-at-the-edge.thegreenhouse.io/demo3) by scrolling to the bottom of the page, with [the code here in GitHub](https://github.com/thescientist13/web-components-at-the-edge/blob/main/serverless/get-demo3/index.mjs)!
+
+```js
+// slider.js
+const template = document.createElement('template');
+
+template.innerHTML = `
+  <style>
+    h6 {
+      color: var(--color-secondary);
+      font-size: 25px;
+    }
+
+    h6.hydrated {
+      animation-duration: 3s;
+      animation-name: slidein;
+    }
+
+    @keyframes slidein {
+      from {
+        margin-left: 100%;
+        width: 300%;
+      }
+
+      to {
+        font-size: 25px;
+      }
+    }
+  </style>
+
+  <h6>This is a slider component.</h6>
+`;
+
+class SliderComponent extends HTMLElement {
+  connectedCallback() {
+    if (!this.shadowRoot) {
+      this.attachShadow({ mode: 'open' });
+      this.shadowRoot.appendChild(template.content.cloneNode(true));
+    } else {
+      const header = this.shadowRoot.querySelector('h6');
+
+      header.style.color = this.getAttribute('color');
+      header.classList.add('hydrated');
+    }
+  }
+}
+
+export { SliderComponent };
+export default SliderComponent;
+
+customElements.define('wc-slider', SliderComponent);
+```
+
+In this case, _index.js_ builds `SliderComponent` from HTML and not only uses the `hydrate` attribute and metadata for lazy hydration, but also can pass in the animated color via a CSS custom property!
+
+```js
+// handler.js
+import { renderFromHTML } from 'wc-compiler';
+
+export async function handler() {
+  const { html, metadata } = await renderFromHTML(`
+    <wc-slider color="var(--color-accent)">
+    </wc-slider>
+  `);
+  const lazyJs = [];
+
+  for (const asset in assets) {
+    const a = assets[asset];
+
+    a.tagName = asset;
+
+    if (a.moduleURL.href.endsWith('.js')) {
+      if (a.hydrate === 'lazy') {
+        lazyJs.push(a);
+      }
+    }
+  }
+
+  return {
+    status: 200,
+    headers: {
+      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0',
+      'content-type': 'text/html; charset=utf8'
+    },
+    body: `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <style>
+            :root, :host {
+              --color-primary: rgb(12, 36, 42);
+              --color-secondary: rgb(110, 176, 6);
+              --color-tertiary: rgb(110, 176, 6);
+              --color-accent: rgb(250, 217, 28);
+            }
+          </style>
+          ${
+            lazyJs.map(script => {
+              return `
+                <script type="module">
+                  let initialized = false;
+
+                  window.addEventListener('load', () => {
+                    const options = {
+                      root: null,
+                      rootMargin: '20px',
+                      threshold: 1.0
+                    }
+
+                    const callback = (entries, observer) => {
+                      entries.forEach(entry => {
+                        if(!initialized && entry.isIntersecting) {
+                          initialized = true;
+                          import('${script.moduleURL.pathname.replace(process.cwd(), '')}')
+                        }
+                      });
+                    }
+
+                    const observer = new IntersectionObserver(callback, options);
+                    const target = document.querySelector('${script.tagName}');
+
+                    observer.observe(target);
+                  })
+                </script>
+              `;
+            }).join('\n')
+          }
+        </head>
+        <body>
+          ${html}
+        </body>
+      </html>
+    `;
+  };
+}
+```
\ No newline at end of file

From c58b8682d755e7f52cc6c286454e314f55b50194 Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Tue, 7 Jun 2022 22:33:26 -0400
Subject: [PATCH 05/10] links and grammar

---
 docs/pages/examples.md | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/docs/pages/examples.md b/docs/pages/examples.md
index d2e72094..383dac24 100644
--- a/docs/pages/examples.md
+++ b/docs/pages/examples.md
@@ -6,7 +6,7 @@ Below are some example of how is **WCC** being used right now.
 
 ## Server Rendering (SSR)
 
-For the project [**Greenwood**](https://github.com/ProjectEvergreen/greenwood), **WCC** is being used to provide a _Next.js_ like experience by allowing users to author server-side route using native custom elements!
+For the project [**Greenwood**](https://github.com/ProjectEvergreen/greenwood/), **WCC** is going to be used to provide a _Next.js_ like experience by allowing users to author [server-side routes using native custom elements](https://www.greenwoodjs.io/docs/server-rendering/#routes)!
 
 ```js
 import '../components/card/card.js';
@@ -36,10 +36,7 @@ export default class ArtistsPage extends HTMLElement {
 
 ## Serverless and Edge Functions
 
-In the talk [_"Web Components at the Edge"_](https://sched.co/11loQ) for OpenJS World 2022, **WCC** was leveraged in both the AWS Lambda serverless functions and Netlify Edge functions demos.  See all the [code, slides and demos in GitHub](https://github.com/thescientist13/web-components-at-the-edge).
-
-
-In addition to entirely server render Web Components with client side hydration (see [here](/examples#progressive-hydration)), it also shows some clever ways to use **WCC** in more constrained environments, like an edge runtime.
+In the talk [_"Web Components at the Edge"_](https://sched.co/11loQ) for OpenJS World 2022, **WCC** was leveraged for all the AWS Lambda serverless function and Netlify Edge function demos.  It also shows some clever ways to use **WCC** in more constrained runtime environments, like an edge runtime.  See all the [code, slides and demos in GitHub](https://github.com/thescientist13/web-components-at-the-edge).
 
 ```js
 import '../../node_modules/wc-compiler/src/dom-shim.js';
@@ -80,13 +77,13 @@ export default async function (request, context) {
 
 ## Static Sites (SSG)
 
-Using `innerHTML`, custom elements can be authored to not use Shadow DOM, which can be useful for a `Layout` or `App` component where that top level content specifically should _not_ be in a shadow root, e.g. `<template>` tag.  What's nice about **WCC** is that by using `innerHTML` or `attachShadow`, you can opt in a per component basis, like we do for [the **WCC** website](https://github.com/thescientist13/wcc/tree/master/docs), where the content is authored in markdown, but the header, navigation, footer are all custom elements rendered to static HTML.
+Using `innerHTML`, custom elements can be authored to not use Shadow DOM, which can be useful for a `Layout` or `App` component where that top level content specifically should _not_ be rendered in a shadow root, e.g. `<template>` tag.  What's nice about **WCC** is that by using `innerHTML` or `attachShadow`, you can opt-in to either on a per component basis, like is being done for [the **WCC** website](https://github.com/ProjectEvergreen/wcc/tree/master/docs).  In this case, the content is authored in markdown, but the header, navigation, footer are all custom elements rendered to static HTML.
 ```js
-// index.js, aka a Layout component
+// index.js
 import './components/footer.js';
 import './components/header.js';
 
-class Home extends HTMLElement {
+class Layout extends HTMLElement {
 
   connectedCallback() {
     this.innerHTML = `
@@ -121,12 +118,12 @@ class Home extends HTMLElement {
   }
 }
 
-export default Home;
+export default Layout;
 ```
 
 ## Progressive Hydration
 
-Using the `metadata` information from a custom element with the `hydrate=true` attribute, you can use use this metadata to use an IntersectionObserver to progressively load a custom element.  See it in [action here](https://wc-at-the-edge.thegreenhouse.io/demo3) by scrolling to the bottom of the page, with [the code here in GitHub](https://github.com/thescientist13/web-components-at-the-edge/blob/main/serverless/get-demo3/index.mjs)!
+Using the `metadata` information from a custom element with the `hydrate=true` attribute, you can use use the metadata with an [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to progressively load a custom element.  See it in [action here](https://wc-at-the-edge.thegreenhouse.io/demo3) by scrolling to the bottom of the page and seeing the animation happen!  View [the code here in GitHub](https://github.com/thescientist13/web-components-at-the-edge/blob/main/serverless/get-demo3/index.mjs).
 
 ```js
 // slider.js

From a64fe023baee9c8e90d363793911e9fea6d08fcb Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Wed, 8 Jun 2022 08:33:19 -0400
Subject: [PATCH 06/10] final review of docs

---
 README.md              | 15 +++++----------
 docs/pages/docs.md     | 22 +++++++++++-----------
 docs/pages/examples.md | 18 ++++++++----------
 docs/pages/index.md    | 25 +++++++++++++------------
 4 files changed, 37 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index 75f617f8..d3250399 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,6 @@
 
 > _Experimental Web Components compiler.  It's Web Components all the way down!_  🐢
 
-## Overview
-
-**Web Components Compiler (WCC)** is a NodeJS package designed to make server-side rendering (SSR) of native Web Components easier.  It can render (within reason 😅) your Web Component into static HTML leveraging [Declarative Shadow DOM](https://web.dev/declarative-shadow-dom/).
-
 ## How It Works
 
 1. Write a Web Component
@@ -64,19 +60,18 @@
     </wcc-footer>
     ```
 
+## Documentation
+
+See our [website](https://merry-caramel-524e61.netlify.app/) for API docs and examples.
+
 ## Installation
 
-**WCC** can be installed from npm.
+**WCC** runs on NodeJS and can be installed from npm.
 
 ```shell
 $ npm install wc-compiler --save-dev
 ```
 
-## Documentation
-
-See our [website](https://merry-caramel-524e61.netlify.app/) for API docs and examples.
-
-
 ## Motivation
 
 **WCC** is not a static site generator, framework or bundler.  It is focused on producing raw HTML from Web Components with the intent of being easily integrated into a site generator or framework, like [**Greenwood**](https://github.com/ProjectEvergreen/greenwood/), the original motivation for creating [this project](https://github.com/ProjectEvergreen/greenwood/issues/935).
diff --git a/docs/pages/docs.md b/docs/pages/docs.md
index 9fdfadd6..edebd3e2 100644
--- a/docs/pages/docs.md
+++ b/docs/pages/docs.md
@@ -48,11 +48,11 @@ class Home extends HTMLElement {
 export default Home;
 ```
 
-> _**Note**: `wcc` will decide to wrap or not wrap your entry point's HTML in a custom element tag if you do or do not, respectively, have a `customElements.define` statement in your entry point.  `wcc` will use the tag name you define as the custom element tag name in the HTML._
+> _**Note**: **WCC** will wrap or not wrap your _entry point's HTML_ in a custom element tag if you do or do not, respectively, include a `customElements.define` in your entry point.  **WCC** will use the tag name you define as the custom element tag name in the generated HTML._
 
 ### renderFromHTML
 
-This function takes a string of HTML and an array of any top-level custom elements used with `import`, and returns the static HTML output of the rendered content.
+This function takes a string of HTML and an array of any top-level custom elements used in the HTML, and returns the static HTML output of the rendered content.
 
 ```js
 const { html } = await renderFromHTML(`
@@ -66,13 +66,15 @@ const { html } = await renderFromHTML(`
       <wcc-footer></wcc-footer>
     </body>
   </html>
-`, 
+`,
 [
   new URL('./src/components/footer.js', import.meta.url),
   new URL('./src/components/header.js', import.meta.url)
 ]);
 ```
 
+For example, even if `Header` or `Footer` use `import` to pull in additional custom elements, only the `Header` and `Footer custom elements used in the "entry" HTML are needed in the array.
+
 ### Options
 
 `renderToString` and `renderFromHTML` also supports a second and third parameter respectively, that is an object, called `options`
@@ -90,7 +92,7 @@ It supports the following configuration(s):
 
 ## Metadata
 
-`renderToString` and `renderFromHTML` return not only HTML, but also metadata about all the custom elements registered as part of rendering the top level custom element.
+`renderToString` and `renderFromHTML` return not only HTML, but also metadata about all the custom elements registered as part of rendering the entry file.
 
 ```js
 const { metadata } = await renderToString(new URL('./src/index.js', import.meta.url));
@@ -104,7 +106,7 @@ console.log({ metadata });
  *     'wcc-navigation': { instanceName: 'Navigation', moduleURL: [URL] }
  *   ]
  * }
- * 
+ *
 ```
 
 ## Progressive Hydration
@@ -114,7 +116,7 @@ To achieve an islands architecture implementation, if you add `hydration="true"`
 <wcc-footer hydration="true"></wcc-footer>
 ```
 
-This will be reflected in the returned `metadata` array from `renderToString`.  
+This will be reflected in the returned `metadata` array from `renderToString`.
 ```js
 /*
  * {
@@ -124,12 +126,12 @@ This will be reflected in the returned `metadata` array from `renderToString`.
  *     'wcc-navigation': { instanceName: 'Navigation', moduleURL: [URL] }
  *   ]
  * }
- * 
+ *
 ```
 
 The benefit is that this hint can be used to defer loading of these scripts by using an [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) (for example), instead of eagerly loading it on page load using a `<script>` tag.
 
-> _See our [examples page](/examples/) for more info._
+> _See [this example](/examples/#progressive-hydration) for more information._
 
 
 ## Data
@@ -145,10 +147,8 @@ export async function getData() {
 }
 ```
 
-> _See our [examples page](/examples/) for more info._
-
 ## Conventions
 
 - Make sure to define your custom elements with `customElements.define`
-- Make sure to `export default` your custom element base class
+- Make sure to include a `export default` for your custom element base class
 - Avoid [touching the DOM in `constructor` methods](https://twitter.com/techytacos/status/1514029967981494280)
\ No newline at end of file
diff --git a/docs/pages/examples.md b/docs/pages/examples.md
index 383dac24..6fcb03f8 100644
--- a/docs/pages/examples.md
+++ b/docs/pages/examples.md
@@ -1,12 +1,12 @@
 # Examples
 
-Below are some example of how is **WCC** being used right now.
+Below are some example of how **WCC** is being used right now.
 
 ## Table of contents
 
 ## Server Rendering (SSR)
 
-For the project [**Greenwood**](https://github.com/ProjectEvergreen/greenwood/), **WCC** is going to be used to provide a _Next.js_ like experience by allowing users to author [server-side routes using native custom elements](https://www.greenwoodjs.io/docs/server-rendering/#routes)!
+For the project [**Greenwood**](https://github.com/ProjectEvergreen/greenwood/), **WCC** is going to be used to provide a _Next.js_ like experience by allowing users to author [server-side routes using native custom elements](https://www.greenwoodjs.io/docs/server-rendering/#routes)!  ✨
 
 ```js
 import '../components/card/card.js';
@@ -36,7 +36,7 @@ export default class ArtistsPage extends HTMLElement {
 
 ## Serverless and Edge Functions
 
-In the talk [_"Web Components at the Edge"_](https://sched.co/11loQ) for OpenJS World 2022, **WCC** was leveraged for all the AWS Lambda serverless function and Netlify Edge function demos.  It also shows some clever ways to use **WCC** in more constrained runtime environments, like an edge runtime.  See all the [code, slides and demos in GitHub](https://github.com/thescientist13/web-components-at-the-edge).
+In the talk [_"Web Components at the Edge"_](https://sched.co/11loQ) for OpenJS World 2022, **WCC** was leveraged for all the AWS Lambda serverless function and Netlify Edge function demos.  It also shows some clever ways to use **WCC** in more constrained runtime environments, like an edge runtime where something like `fs` might not be available.  See all the [code, slides and demos in GitHub](https://github.com/thescientist13/web-components-at-the-edge).  🚀
 
 ```js
 import '../../node_modules/wc-compiler/src/dom-shim.js';
@@ -53,9 +53,6 @@ export default async function (request, context) {
   const response = new Response(`
     <!DOCTYPE html>
     <html lang="en">
-      <head>
-        ...
-      </head>
       <body>
         <wc-greeting>
           ${greeting.getInnerHTML({ includeShadowRoots: true })}
@@ -77,7 +74,8 @@ export default async function (request, context) {
 
 ## Static Sites (SSG)
 
-Using `innerHTML`, custom elements can be authored to not use Shadow DOM, which can be useful for a `Layout` or `App` component where that top level content specifically should _not_ be rendered in a shadow root, e.g. `<template>` tag.  What's nice about **WCC** is that by using `innerHTML` or `attachShadow`, you can opt-in to either on a per component basis, like is being done for [the **WCC** website](https://github.com/ProjectEvergreen/wcc/tree/master/docs).  In this case, the content is authored in markdown, but the header, navigation, footer are all custom elements rendered to static HTML.
+Using `innerHTML`, custom elements can be authored to not use Shadow DOM, which can be useful for a `Layout` or `App` component where that top level content specifically should _not_ be rendered in a shadow root, e.g. `<template>` tag.  What's nice about **WCC** is that by using `innerHTML` or `attachShadow`, you can opt-in to either on a per component basis, like is being done for [the **WCC** website](https://github.com/ProjectEvergreen/wcc/tree/master/docs).  In this case, the content is authored in markdown, but the layout, header, navigation, and footer are all custom elements rendered to static HTML.  🗒️
+
 ```js
 // index.js
 import './components/footer.js';
@@ -123,7 +121,9 @@ export default Layout;
 
 ## Progressive Hydration
 
-Using the `metadata` information from a custom element with the `hydrate=true` attribute, you can use use the metadata with an [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to progressively load a custom element.  See it in [action here](https://wc-at-the-edge.thegreenhouse.io/demo3) by scrolling to the bottom of the page and seeing the animation happen!  View [the code here in GitHub](https://github.com/thescientist13/web-components-at-the-edge/blob/main/serverless/get-demo3/index.mjs).
+Using the `metadata` information from a custom element with the `hydrate=true` attribute, you can use use the metadata with an [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to progressively load a custom element.  In this case, _handler.js_ builds `SliderComponent` from HTML and not only uses the `hydrate` attribute and metadata for lazy hydration, but also passes in the animated color via a CSS custom property set at build time!  🤯
+
+See it in [action here](https://wc-at-the-edge.thegreenhouse.io/demo3) by scrolling to the bottom of the page and seeing the animation happen!  View [the code here in GitHub](https://github.com/thescientist13/web-components-at-the-edge/blob/main/serverless/get-demo3/index.mjs).
 
 ```js
 // slider.js
@@ -176,8 +176,6 @@ export default SliderComponent;
 customElements.define('wc-slider', SliderComponent);
 ```
 
-In this case, _index.js_ builds `SliderComponent` from HTML and not only uses the `hydrate` attribute and metadata for lazy hydration, but also can pass in the animated color via a CSS custom property!
-
 ```js
 // handler.js
 import { renderFromHTML } from 'wc-compiler';
diff --git a/docs/pages/index.md b/docs/pages/index.md
index 5e01c7c0..554ebfef 100644
--- a/docs/pages/index.md
+++ b/docs/pages/index.md
@@ -1,14 +1,6 @@
 # Introduction
 
-**Web Components Compiler (WCC)** is a NodeJS package designed to make server-side rendering (SSR) of native Web Components easier.  It can render (within reason 😅) your Web Component into static HTML leveraging [Declarative Shadow DOM](https://web.dev/declarative-shadow-dom/).
-
-## Installation
-
-**WCC** can be installed from npm.
-
-```shell
-$ npm install wc-compiler --save-dev
-```
+**Web Components Compiler (WCC)** is a NodeJS package designed to make server-side rendering (SSR) of native Web Components easier.  It can render (within reason 😅) your Web Component into static HTML.  This includes support for [Declarative Shadow DOM](https://web.dev/declarative-shadow-dom/).
 
 ## Key Features
 
@@ -20,12 +12,21 @@ $ npm install wc-compiler --save-dev
     - `[get|set|has]Attribute`
 1. `<template>` / `DocumentFragment`
 1. Recursive rendering of nested custom elements
-1. Optional Declarative Shadow DOM (for producing purely content driven static pages)
-1. Metadata and runtime hints to support progressive hydration and lazy loading strategies
+1. Metadata and runtime hints to support various progressive hydration and lazy loading strategies
+
+## Installation
+
+**WCC** can be installed from npm.
+
+```shell
+$ npm install wc-compiler --save-dev
+```
 
 ## Usage
 
-**WCC** exposes a few utilities to render your Web Components.  See [our API docs](/docs) for all available features.
+**WCC** provides a couple options for rendering your Web Components.
+
+> _See [our API docs](/docs) for all available features and [our examples](/examples) for various use cases._
 
 1. Given a custom element like so:
     ```js

From 6ec513a4c4b1b759db52af8aec547acf70817dbf Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Wed, 8 Jun 2022 08:33:36 -0400
Subject: [PATCH 07/10] rename index to layout

---
 build.js                     | 9 ++++-----
 docs/{index.js => layout.js} | 4 ++--
 2 files changed, 6 insertions(+), 7 deletions(-)
 rename docs/{index.js => layout.js} (92%)

diff --git a/build.js b/build.js
index c4f51dd8..755f2ddf 100644
--- a/build.js
+++ b/build.js
@@ -15,7 +15,7 @@ async function init() {
   const distRoot = './dist';
   const pagesRoot = './docs/pages';
   const pages = await fs.readdir(new URL(pagesRoot, import.meta.url));
-  const { html } = await renderToString(new URL('./docs/index.js', import.meta.url), {
+  const { html } = await renderToString(new URL('./docs/layout.js', import.meta.url), {
     lightMode: true
   });
 
@@ -29,8 +29,10 @@ async function init() {
   await fs.copyFile(new URL('./docs/assets/favicon.ico', import.meta.url), new URL(`${distRoot}/favicon.ico`, import.meta.url));
 
   for (const page of pages) {
+    const route = page.replace('.md', '');
+    const outputPath = route === 'index' ? '' : `${route}/`;
     const markdown = await fs.readFile(new URL(`${pagesRoot}/${page}`, import.meta.url), 'utf-8');
-    let content = (await unified()
+    const content = (await unified()
       .use(remarkParse)
       .use(remarkToc, { tight: true })
       .use(remarkRehype, { allowDangerousHtml: true })
@@ -41,9 +43,6 @@ async function init() {
       .use(rehypeStringify)
       .process(markdown)).value;
 
-    const route = page.replace('.md', '');
-    const outputPath = route === 'index' ? '' : `${route}/`;
-
     await fs.mkdir(`./dist/${outputPath}`, { recursive: true });
     await fs.mkdir(`${distRoot}/${outputPath}`, { recursive: true });
 
diff --git a/docs/index.js b/docs/layout.js
similarity index 92%
rename from docs/index.js
rename to docs/layout.js
index 9e499877..12e40a0f 100644
--- a/docs/index.js
+++ b/docs/layout.js
@@ -35,7 +35,7 @@ template.innerHTML = `
   <wcc-footer></wcc-footer>
 `;
 
-class Home extends HTMLElement {
+class Layout extends HTMLElement {
 
   connectedCallback() {
     if (!this.shadowRoot) {
@@ -45,4 +45,4 @@ class Home extends HTMLElement {
   }
 }
 
-export default Home;
+export default Layout;
\ No newline at end of file

From 51c6fcd8adfd6a8b86459f7524e6b0ae9582067e Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Tue, 7 Jun 2022 21:24:27 -0400
Subject: [PATCH 08/10] clean up README and decouple home page from README

---
 README.md           |  8 ++++----
 docs/pages/index.md | 20 +++++++++-----------
 2 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index d3250399..d770999c 100644
--- a/README.md
+++ b/README.md
@@ -60,10 +60,6 @@
     </wcc-footer>
     ```
 
-## Documentation
-
-See our [website](https://merry-caramel-524e61.netlify.app/) for API docs and examples.
-
 ## Installation
 
 **WCC** runs on NodeJS and can be installed from npm.
@@ -72,6 +68,10 @@ See our [website](https://merry-caramel-524e61.netlify.app/) for API docs and ex
 $ npm install wc-compiler --save-dev
 ```
 
+## Documentation
+
+See our [website](https://merry-caramel-524e61.netlify.app/) for API docs and examples.
+
 ## Motivation
 
 **WCC** is not a static site generator, framework or bundler.  It is focused on producing raw HTML from Web Components with the intent of being easily integrated into a site generator or framework, like [**Greenwood**](https://github.com/ProjectEvergreen/greenwood/), the original motivation for creating [this project](https://github.com/ProjectEvergreen/greenwood/issues/935).
diff --git a/docs/pages/index.md b/docs/pages/index.md
index 554ebfef..e5a4e18e 100644
--- a/docs/pages/index.md
+++ b/docs/pages/index.md
@@ -2,6 +2,14 @@
 
 **Web Components Compiler (WCC)** is a NodeJS package designed to make server-side rendering (SSR) of native Web Components easier.  It can render (within reason 😅) your Web Component into static HTML.  This includes support for [Declarative Shadow DOM](https://web.dev/declarative-shadow-dom/).
 
+## Installation
+
+**WCC** can be installed from npm.
+
+```shell
+$ npm install wc-compiler --save-dev
+```
+
 ## Key Features
 
 1. Supports the following `HTMLElement` lifecycles and methods on the server side
@@ -14,19 +22,9 @@
 1. Recursive rendering of nested custom elements
 1. Metadata and runtime hints to support various progressive hydration and lazy loading strategies
 
-## Installation
-
-**WCC** can be installed from npm.
-
-```shell
-$ npm install wc-compiler --save-dev
-```
-
 ## Usage
 
-**WCC** provides a couple options for rendering your Web Components.
-
-> _See [our API docs](/docs) for all available features and [our examples](/examples) for various use cases._
+**WCC** exposes a few utilities to render your Web Components.  See [our API docs](/docs) for all available features.
 
 1. Given a custom element like so:
     ```js

From 124c0f3d83cb51f6ec9607618c5f06c5bc989906 Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Tue, 7 Jun 2022 22:24:32 -0400
Subject: [PATCH 09/10] examples first draft

---
 docs/pages/examples.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/pages/examples.md b/docs/pages/examples.md
index 6fcb03f8..cf71f4a2 100644
--- a/docs/pages/examples.md
+++ b/docs/pages/examples.md
@@ -77,12 +77,11 @@ export default async function (request, context) {
 Using `innerHTML`, custom elements can be authored to not use Shadow DOM, which can be useful for a `Layout` or `App` component where that top level content specifically should _not_ be rendered in a shadow root, e.g. `<template>` tag.  What's nice about **WCC** is that by using `innerHTML` or `attachShadow`, you can opt-in to either on a per component basis, like is being done for [the **WCC** website](https://github.com/ProjectEvergreen/wcc/tree/master/docs).  In this case, the content is authored in markdown, but the layout, header, navigation, and footer are all custom elements rendered to static HTML.  🗒️
 
 ```js
-// index.js
+// layout.js
 import './components/footer.js';
 import './components/header.js';
 
 class Layout extends HTMLElement {
-
   connectedCallback() {
     this.innerHTML = `
       <style>

From 79a8d257531bf5476326bd41fd18f231ef0eb928 Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Wed, 8 Jun 2022 08:45:39 -0400
Subject: [PATCH 10/10] account for large nav text on mobile

---
 docs/components/navigation.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/components/navigation.js b/docs/components/navigation.js
index ba89e729..35ff41c7 100644
--- a/docs/components/navigation.js
+++ b/docs/components/navigation.js
@@ -7,6 +7,7 @@ template.innerHTML = `
       list-style-type: none;
       overflow: auto;
       grid-column: 1 / -1;
+      width: 90%;
     }
 
     nav ul li {
@@ -18,7 +19,6 @@ template.innerHTML = `
     nav ul li a, nav ul li a:visited {
       display: inline-block;
       color: #efefef;
-      min-width: 48px;
       min-height: 48px;
       font-size: 2.5rem;
     }