Reorganizing new docs menu/files (#1662)

* reorganizing pages * moving files around * minor edits, putting links back in
FredKSchott · Nov 19, 2020 · 3fc6cf0 · 3fc6cf0
1 parent 4f344ce
commit 3fc6cf0
Show file tree

Hide file tree

Showing 12 changed files with 145 additions and 230 deletions.
diff --git a/www/_includes/layouts/menu.njk b/www/_includes/layouts/menu.njk
@@ -1,48 +1,43 @@
 <nav class="menu">
-
   <ol>
-
     <li>
       <span class="menu-section-header">Concepts</span>
       <ol>
         <li>
-          <a href="/#">How Snowpack Works</a>
+          <a href="/about">How Snowpack Works</a>
         </li>
         <li>
-          <a href="/#">The Dev Server</a>
+          <a href="/#">Unbundled Development</a>
         </li>
         <li>
           <a href="/#">The Build Pipeline</a>
         </li>
+        <li>
+          <a href="/#">The Dev Server</a>
+        </li>
       </ol>
     </li>
 
     <li>
       <span class="menu-section-header">Getting Started</span>
       <ol>
         <li>
-          <a href="/#">Install Snowpack</a>
-        </li>
-        <li>
-          <a href="/getting-started">Quick Start</a>
-        </li>
-        <li>
-          <a href="/guides/react">React</a>
+          <a href="/tutorials/getting-started">Tutorial</a>
         </li>
         <li>
-          <a href="/guides/preact">Preact</a>
+          <a href="/tutorials/quick-start">Quick Start</a>
         </li>
         <li>
-          <a href="/guides/svelte">Svelte</a>
-        </li>
-        <li>
-          <a href="/guides/vue">Vue</a>
+          <a href="/tutorials/react">React</a>
         </li>
+        <li>Preact (coming soon)</li>
+        <li>Svelte (coming soon)</li>
+        <li>Vue (coming soon)</li>
       </ol>
     </li>
 
     <li>
-      <span class="menu-section-header">Integration Guides</span>
+      <span class="menu-section-header">Guides</span>
       <ol>
         <li>
           <a href="/#">Sass</a>
@@ -60,36 +55,38 @@
     </li>
 
     <li>
-      <span class="menu-section-header">Usage</span>
+      <span class="menu-section-header">Reference</span>
       <ol>
+        <li>
+          <a href="/reference/features">Features</a>
+        </li>
         <li>
           <a href="/configuration">CLI</a>
         </li>
         <li>
           <a href="/configuration">JavaScript API</a>
         </li>
         <li>
-          <a href="/guides/plugins">Plugin API</a>
+          <a href="/reference/plugins">Plugin API</a>
         </li>
         <li>
-          <a href="/configuration">snowpack.config.js</a>
+          <a href="/reference/configuration">snowpack.config.js</a>
         </li>
       </ol>
     </li>
 
     <li>
-      <a href="/plugins">
-        <span class="menu-section-header">Plugins</span></a>
+      <a href="/plugins"> <span class="menu-section-header">Plugins</span></a>
     </li>
 
     <li>
-      <a href="/support">
-        <span class="menu-section-header">Support</span></a>
+      <a href="/support"> <span class="menu-section-header">Support</span></a>
     </li>
 
     <li>
       <a href="/community">
-        <span class="menu-section-header">Community</span></a>
+        <span class="menu-section-header">Community</span></a
+      >
     </li>
   </ol>
-</nav>
+</nav>
diff --git a/www/_template/guides/ssl.md b/www/_template/guides/ssl.md
@@ -0,0 +1,13 @@
+---
+layout: layouts/main.njk
+title: SSL Certificates
+---
+
+## Generating SSL Certificates
+
+You can automatically generate credentials for your project via either:
+
+- [devcert (no install required)](https://github.com/davewasmer/devcert-cli): `npx devcert-cli generate localhost`
+- [mkcert (install required)](https://github.com/FiloSottile/mkcert): `mkcert -install && mkcert -key-file snowpack.key -cert-file snowpack.crt localhost`
+
+In most situations you should add personally generated certificate files (`snowpack.key` and `snowpack.crt`) to your `.gitignore` file.
diff --git a/www/_template/guides/ssr.md b/www/_template/guides/ssr.md
@@ -0,0 +1,34 @@
+---
+layout: layouts/main.njk
+title: SSR
+---
+
+SSR for Snowpack is supported but fairly new and experimental. This documentation will be updated as we finalize support over the next few minor versions.
+
+```js
+// New in Snowpack v2.15.0 - JS API Example
+import {startDevServer} from 'snowpack';
+const server = await startDevServer({ ... });
+```
+
+These frameworks have known experiments / examples of using SSR + Snowpack:
+
+- React (Example): https://github.com/matthoffner/snowpack-react-ssr
+- Svelte/Sapper (Experiment): https://github.com/Rich-Harris/snowpack-svelte-ssr
+- [Join our Discord](https://discord.gg/rS8SnRk) if you're interested in getting involved!
+
+To connect your own server to `snowpack dev` for SSR, there are a few things that you'll need to set up. Make sure that you include any Snowpack-built resources via script tags in your server's HTML response:
+
+```html
+<!-- Example: Create Snowpack App builds your src/ directory to the /_dist_/* directory -->
+<script type="module" src="http://localhost:8080/_dist_/index.js"></script>
+```
+
+And make sure that your HTML response also includes code to configure HMR to talk to Snowpack's dev server:
+
+```html
+<!-- Configure Snowpack's HMR connection yourself, somewhere on your page HTML -->
+<script>
+  window.HMR_WEBSOCKET_URL = 'ws://localhost:8080';
+</script>
+```
diff --git a/www/_template/guides/testing.md b/www/_template/guides/testing.md
@@ -4,6 +4,21 @@ title: Testing
 tags: guides
 ---
 
+Snowpack supports any popular JavaScript testing framework that you're already familiar with. Mocha, Jest, Jasmine, AVA and Cypress are all supported in Snowpack applications.
+
+We currently recommend [@web/test-runner](https://www.npmjs.com/package/@web/test-runner) (WTR) for testing in Snowpack projects. When benchmarked it performed faster than Jest (our previous recommendation) while also providing an environment for testing that more closely matches the actual browser that your project runs in. Most importantly, WTR runs the same Snowpack build pipeline that you've already configured for your project, so there's no extra build configuration needed to run your tests. Jest (and many others) ask you to configure a totally secondary build pipeline for your tests, which reduces test confidence while adding 100s of extra dependencies to your project.
+
+To use [@web/test-runner](https://www.npmjs.com/package/@web/test-runner) in your project, [follow the instructions here](https://modern-web.dev/docs/test-runner/overview/) and make sure that you add the Snowpack plugin to your config file:
+
+```js
+// web-test-runner.config.js
+module.exports = {
+  plugins: [require('@snowpack/web-test-runner-plugin')()],
+};
+```
+
+[See an example setup](https://github.com/snowpackjs/snowpack/blob/main/create-snowpack-app/app-template-react) in on of our Create Snowpack App starter templates.
+
 ### @web/test-runner
 
 [@web/test-runner](https://www.npmjs.com/package/@web/test-runner) is our recommended test runner for Snowpack projects. [See our section on testing](/#testing) for detailed instructions on how to get started with @web/test-runner.

diff --git a/www/_template/configuration.md → www/_template/reference/configuration.md b/www/_template/configuration.md → www/_template/reference/configuration.md