Docs/v0.26.0 updates and revisions (#965)

* update getting started guide and about sections with introduction of WCC

* move puppeteer specific caveats to puppeteer plugin README

* remove errant character

* misc grammar and editing

packages/plugin-renderer-puppeteer/README.md

@@ -2,13 +2,51 @@
 
 ## Overview
 
-A Greenwood plugin for using [**Puppeteer**](https://pptr.dev) as a custom [pre-rendering solution](/docs/server-rendering/#render-vs-prerender).  As Puppeteer is a headless browser, it provides a lot more power and capabilities for fully rendering things like Web Components Web Components, GraphQL calls, and other very browser dependent features.
+A Greenwood plugin for using [**Puppeteer**](https://pptr.dev) as a custom [_pre-rendering_ solution](/docs/server-rendering/#render-vs-prerender).  As Puppeteer is a headless browser, it provides a lot more power and capabilities for fully rendering things like Web Components, GraphQL calls, and other very browser dependent features.
 
 ### Caveats
 
+#### Limitations
 Given this plugin instruments an entire browser, this plugin _only_ supports Greenwood's [`prerender` configuration](/docs/configuration/#prerender) option and so will NOT be viable for any [SSR](/docs/server-rendering/) or [Serverless and Edge](https://github.com/ProjectEvergreen/greenwood/discussions/626) features.  Instead, Greenwood will be focusing on making [**WCC**](https://github.com/ProjectEvergreen/wcc) the default and recommended first-party solution.
 
-> This package assumes you already have `@greenwood/cli` installed.
+#### Dependencies
+
+You may need to install additional Operating System level libraries and dependencies depending on the system you are running on to support headless Chrome. For example, for a Docker based environment like [GitHub Actions](https://github.com/ProjectEvergreen/greenwood/blob/master/.github/workflows/master.yml#L19), you would need to add [this below setup script (or similar)](https://github.com/ProjectEvergreen/greenwood/blob/master/.github/workflows/chromium-lib-install.sh) to your runner
+```shell
+#!/usr/bin/bash
+
+# path/to/your/chromium-lib-install.sh
+sudo apt-get update \\
+  && sudo apt-get install -yq libgconf-2-4 \\
+  && sudo apt-get install -y wget --no-install-recommends \\
+  && sudo wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add - \\
+  && sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \\
+  && sudo apt-get update \\
+  && sudo apt-get install -y google-chrome-unstable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf --no-install-recommends \\
+  && sudo rm -rf /var/lib/apt/lists/*
+```
+
+```yml
+
+.
+.
+
+jobs:
+ build:
+   runs-on: ubuntu-latest
+   steps:
+      - uses: actions/checkout@v1
+      - name: Install Chromium Library Dependencies
+        run: |
+         sh path/to/your/chromium-lib-install.sh
+      - uses: actions/setup-node@v1
+        with:
+           node-version: "14.x"
+      .
+      .
+```
+
+See the Puppeteer [Troubleshooting docs](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md) for more info on setting up your specific environment.
 
 ## Installation
 
@@ -22,6 +60,8 @@ npm install @greenwood/plugin-renderer-puppeteer --save-dev
 yarn add @greenwood/plugin-renderer-puppeteer --dev
 ```
 
+> This package assumes you already have `@greenwood/cli` installed.
+
 ## Usage
 Add this plugin to your _greenwood.config.js_.
 

www/pages/about/features.md

@@ -19,7 +19,9 @@ At the heart of Greenwood is an "evergreen" build, that aims to deliver the most
 
 For example, during development, we keep things lean and tooling free (relatively) by crawling your project's _package.json_ for all your dependencies and then generating an [`importMap`](https://github.com/WICG/import-maps) from that to resolve dependencies on the fly without the need for up front bundling. During production, we optimize and minify your code and get it ready to deploy to the web.
 
-> _You can vist [this page](/about/how-it-works/) to learn more about how Greenwood works under the hood._
+In addition, Greenwood wants to make server rendering a site is as easy as statically hosting it.  Through our SSR and pre-rendering mechanism for Web Components, you can ship less JavaScript and more HTML where you need it.  We're helping to take [Web Components to the Edge](https://github.com/thescientist13/web-components-at-the-edge)!
+
+> _You can visit [this page](/about/how-it-works/) to learn more about how Greenwood works under the hood._
 
 ### Performance
 We believe delivering a great user experience is above all else the most crucial element to a successful web project and part of that means performance out of the box.  Greenwood wants to help your site be one of the fastest out there and so we'll take care of all those optimizations for you, ensuring your site gets a great score in tools like [Lighthouse](https://developers.google.com/web/tools/lighthouse/), one of our primary performance benchmarking tools.

www/pages/about/how-it-works.md

@@ -30,7 +30,7 @@ For _production_ builds:
 - Combine all your code and dependencies into efficient modern bundles including minifying your JavaScript and CSS.
 - Optimizes loading of JavaScript and CSS assets using web hints like `preload` and `prefetch`.
 - Provides the option to server render or pre-render your JavaScript (e.g. Web Components) to static HTML using [**WCC**](https://github.com/ProjectEvergreen/wcc) as a means of providing a fully web standards based templating solution.
-- Can [support](/docs/layouts/) a static site (SSG) or server rendered site (SSR), or a hybrid of the two!  Single Page Application's (SPA) also welcome!
+- Can [support](/docs/layouts/) a static site (SSG) or server rendered site (SSR), or a hybrid of the two!  Single Page Applications (SPA) also welcome!
 - Supports [further optimization](/docs/config#optimization) for additional hints like inlining or only statically pre-rendering JavaScript with no runtime cost.
 
 Lastly, Greenwood aims to be a low point of friction as part of a standard development workflow.  In this way, there will be a balance between what tools and dependencies are considered core to Greenwood.  We aim to avoid the common "meta" framework paradigm and instead want to hone in on a lean and efficient core with good extension points for longer term maintainability and technical design.

www/pages/blog/release/v0-24-0.md

@@ -45,7 +45,7 @@ export default {
   meta: [
     { name: 'description', content: 'The website for my blog and portfolio.' },
     { name: 'twitter:site', content: '@Username' },
-    { rel: 'icon', href: F'/favicon.ico' }
+    { rel: 'icon', href: '/favicon.ico' }
     ...
   ]
 };

www/pages/getting-started/branding.md

@@ -19,22 +19,15 @@ In this section, we will add the following to your project:
 For this guide, we'll use a "vanilla" custom element for our footer.
 
 Start by creating a file called _src/components/footer.js_ with the following code in it.
+
 ```javascript
 class FooterComponent extends HTMLElement {
-  constructor() {
-    super();
-
-    // creates a Shadow DOM root
-    this.root = this.attachShadow({ mode: 'closed' });
-  }
-
-  // run some code when the component is ready
-  // like initializing our component's DOM / innerHTML
+  // run some code to set HTML when the component is ready
   connectedCallback() {
-    this.root.innerHTML = this.getTemplate();
+    this.innerHTML = this.getTemplate();
   }
 
-  // create templates that can interpolate variables and HTML!
+  // create templates that interpolate variables and HTML!
   getTemplate() {
     const year = new Date().getFullYear();
 
@@ -120,20 +113,14 @@ Within our components, we can easily add some styles right within the component
 
 ```javascript
 class FooterComponent extends HTMLElement {
-  constructor() {
-    super();
-
-    this.root = this.attachShadow({ mode: 'closed' });
-  }
-
   connectedCallback() {
-    this.root.innerHTML = this.getTemplate();
+    this.innerHTML = this.getTemplate();
   }
 
   getTemplate() {
     return `
       <style>
-        :host footer {
+        footer {
           color: blue;
         }
       </style>
@@ -151,4 +138,4 @@ customElements.define('app-footer', FooterComponent);
 Taking this all the way with [the code from companion repo](https://vuejs.org/v2/guide/single-file-components.html), you should be able to get a result that looks like this:
 ![greenwood-getting-started-styled](/assets/getting-started-repo-styled.png)
 
-Phew!!  What a journey, but now you have a blog ready to publish!  The last step is to build  and host your project, so let's move on to the [build and deploy section](/getting-started/build-and-deploy/) and make it happen!
+Phew!!  What a journey, but now you have a blog ready to publish!  The last step is to build and host your project, so let's move on to the [build and deploy section](/getting-started/build-and-deploy/) and make it happen!

www/pages/getting-started/optimizing.md

@@ -8,15 +8,15 @@ linkheadings: 3
 
 ## Optimizing
 
-I've you picked up on the fact that we had been showing examples of using Web Components (JavaScript) to write static HTML, like in [the header](https://github.com/ProjectEvergreen/greenwood-getting-started/blob/master/src/components/header/header.js).
+Going through this guide, you may have picked up on the fact that we had been showing examples of using Web Components (JavaScript) to write static HTML, like with [the footer](https://github.com/ProjectEvergreen/greenwood-getting-started/blob/master/src/components/footer/footer.js) we created earlier in [this guide](/getting-started/branding/#templating).
 
 Then that was both intentional, but also means you have a keen eye!
 
 So yes, while for something like what we demonstrated here would have technically been better done as plain HTML (and we would recommend that!), Greenwood understands the value JavaScript can bring to _generating_ HTML.  Which is the whole reason we built Greenwood in the first place. 💚
 
 ### Prerendering
 
-Greenwood provides a default browser-based rendering solution for generating HTML from JavaScript that is specially optimized for Web Components.
+Greenwood provides a built-in Web Component server-rendering solution for generating HTML from JavaScript that is specially optimized for Web Components, called [**WCC**](https://github.com/ProjectEvergreen/wcc).  Below is how to easily opt-in to generating pure HTML from your JS.  Static generation ftw!  
 
 By adding a _greenwood.config.js_ file at the root of your project and setting the `prerender` option to `true`
 ```js
@@ -25,49 +25,47 @@ export default {
 }
 ```
 
-When running the build you will now see static HTML with the content and styles of the header component in _index.html_!
+Then, for each component, you will to export the `class` definition as a default export.
+```js
+# before
+class FooterComponent extends HTMLElement {
+  /* ... */
+}
+
+# after
+export default class FooterComponent extends HTMLElement {
+  /* ... */
+}
+```
+
+Now, when running the build you will see static HTML with the content and styles of the `FooterComponent` component in the output of the _index.html_!
 ```html
-<app-header>
-  <style class="style-scope app-header">
-    .header {
-      background-color: #192a27;
-      min-height: 30px;
-      padding: 10px;
-      font-size: 1.2rem;
+<app-footer>
+  <style>
+    footer {
+      color: blue;
     }
-
-    /* ... */
   </style>
 
-  <header class="header style-scope app-header">
-    <div class="head-wrap style-scope app-header">
-      <div class="brand style-scope app-header">
-        <a href="/" class="style-scope app-header">
-          <img src="/assets/greenwood-logo.png" alt="Greenwood logo" class="style-scope app-header">
-          <h4 class="style-scope app-header">My Personal Blog</h4>
-        </a>
-      </div>
-      <div class="social style-scope app-header">
-        <a href="https://github.com/ProjectEvergreen/greenwood" class="style-scope app-header">
-          <img src="https://img.shields.io/github/stars/ProjectEvergreen/greenwood.svg?style=social&amp;logo=github&amp;label=github" alt="Greenwood GitHub badge" class="github-badge style-scope app-header">
-        </a>
-      </div>
-    </div>
-  </header>
+  <footer>
+    <h4>My Blog &copy;2022</h4>
+  </footer>
 </app-header>
 ```
 
 Awesome, now we're getting somewhere!  But, now you may point out, the JavaScript for the header is still being sent to the page from the `<script>` tag.  Wouldn't it be redundant now?  Well, glad you asked and to that we say, we got that covered there too!  Let's check out the next section. 👇
 
 ### Static Optimization
 
-So with the above, we're now able to prerender the initial HTML content of our Web Components.  Great!  But in cases where all that is needed is a single-pass render, like in the case of this header, or a list, or logic that only needs to run once to generate the desired HTML, Greenwood provides a custom `data-` attribute that you can add to your `<script>` tags to handle just this case.
+So with the above, we're now able to prerender the initial HTML content of our Web Components.  Great!  But in cases where all that is needed is a single-pass render, like in the case of this footer, or a list, or basically any logic that only needs to run once to generate the desired HTML , Greenwood provides a custom `data-` attribute that you can add to your `<script>` tags to handle just this case.
 ```html
-<script type="module" data-gwd-opt="static" src="../components/header/header.js"></script>
+<script type="module" data-gwd-opt="static" src="/components/footer/footer.js"></script>
 ```
 
 By adding `data-gwd-opt="static"`, this `<script>` is removed from the final output of your page leaving you with all the HTML, with none of the runtime JavaScript.  Look at that network tab.  Easy!
 
 ![Greenwood Getting Started optimized](/assets/greenwood-getting-started-repo-optimized.webp)
 
+> _You may have also noticed we are not using Declarative Shadow DOM.  This is also intentional.  DSD is not supported in all browsers, plus this is static content we intending to generate and we don't want to ship that inside an inert `<template>` tag.  However, for interactive content that is intended to hydrate client side, then definitely!  See our [release blog post section on **WCC**](/blog/release/v0-26-0#wcc) for a little more context on this distinction._
+
 Ok, let's [wrap this all up](/getting-started/next-steps/) and get you onto learning more about all the options and feature of using Greenwood to build your next project!

www/pages/getting-started/quick-start.md

@@ -56,7 +56,7 @@ Done!
 
 ### Stackblitz
 
-Greenwood thinks there's a world where you never have to leave the browser to build and author content for your site, and after you see our starter working [in Stackblitz](https://stackblitz.com/github/projectevergreen/greenwood-getting-started?embed=1), we think you'll be a believer too!
+Greenwood thinks there's a world where you never have to leave the browser to build and author content for your site, and after you see our starter working [in Stackblitz](https://stackblitz.com/github/projectevergreen/greenwood-getting-started), we think you'll be a believer too!
 
 <iframe src="https://stackblitz.com/github/projectevergreen/greenwood-getting-started?embed=1" class="stackblitz" loading="lazy"></iframe>
 

www/pages/guides/cloudflare-workers-deployment.md

@@ -82,9 +82,6 @@ jobs:
       - uses: actions/checkout@v1
       - name: Navigate to repo
         run: cd $GITHUB_WORKSPACE
-      - name: Install Chromium Library Dependencies
-        run: |
-         sh ./.github/workflows/chromium-lib-install.sh
       - uses: actions/setup-node@v1
         with:
            node-version: "14.x"
@@ -100,19 +97,5 @@ jobs:
            environment: "production"
 ```
 
-In the same directory as main.yml create a file 'chromium-lib-install.sh'
-
-```bash
-#!/usr/bin/bash
-
-sudo apt-get update \\
-  && sudo apt-get install -yq libgconf-2-4 \\
-  && sudo apt-get install -y wget --no-install-recommends \\
-  && sudo wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add - \\
-  && sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \\
-  && sudo apt-get update \\
-  && sudo apt-get install -y google-chrome-unstable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf --no-install-recommends \\
-  && sudo rm -rf /var/lib/apt/lists/*
-```
 
 Push your updates to your repo and the action will begin automatically. This will create a new worker with the name from the toml file -production (IE demo-production), make sure custom url is attached to this worker.

www/pages/guides/firebase.md

@@ -81,9 +81,6 @@ jobs:
 
     steps:
     - uses: actions/checkout@v1
-    - name: Install Chromium Library Dependencies
-      run: |
-       sh ./.github/workflows/chromium-lib-install.sh
     - name: Build
       run: |
         npm install
@@ -94,19 +91,4 @@ jobs:
         firebase deploy --token ${{ secrets.FIREBASE_TOKEN }} -P your-firebase-project-name
 ```
 
-In the same directory as main.yml create a file 'chromium-lib-install.sh'
-
-```bash
-#!/usr/bin/bash
-
-sudo apt-get update \\
-  && sudo apt-get install -yq libgconf-2-4 \\
-  && sudo apt-get install -y wget --no-install-recommends \\
-  && sudo wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add - \\
-  && sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \\
-  && sudo apt-get update \\
-  && sudo apt-get install -y google-chrome-unstable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf --no-install-recommends \\
-  && sudo rm -rf /var/lib/apt/lists/*
-```
-
 Now every change to the master branch will compile and push your code to firebase.

www/pages/guides/s3-cloudfront.md

@@ -66,9 +66,6 @@ jobs:
       - uses: actions/checkout@v1
       - name: Navigate to repo
         run: cd $GITHUB_WORKSPACE
-      - name: Install Chromium Library Dependencies
-        run: |
-         sh ./.github/workflows/chromium-lib-install.sh
       - uses: actions/setup-node@v1
         with:
           node-version: "14.x"
@@ -87,19 +84,4 @@ jobs:
           OPTIONS: "--acl public-read"
 ```
 
-In the same directory as main.yml create a file 'chromium-lib-install.sh'
-
-```bash
-#!/usr/bin/bash
-
-sudo apt-get update \\
-  && sudo apt-get install -yq libgconf-2-4 \\
-  && sudo apt-get install -y wget --no-install-recommends \\
-  && sudo wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add - \\
-  && sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \\
-  && sudo apt-get update \\
-  && sudo apt-get install -y google-chrome-unstable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf --no-install-recommends \\
-  && sudo rm -rf /var/lib/apt/lists/*
-```
-
 Push your updates to your repo and the action will begin automatically.