Update Getting Started

website/documents/guides/01-getting-started.md

@@ -2,11 +2,14 @@
 title: Getting Started
 ---
 
+<!-- Try to use absolute links so this can be copied to the package README. -->
+
 ## Try Crank
 
 The fastest way to try Crank is via the [online playground](https://crank.js.org/playground). In addition, many of the code examples in these guides feature live previews.
 
 ## Installation
+
 The Crank package is available on [NPM](https://npmjs.org/@b9g/crank) through
 the [@b9g organization](https://www.npmjs.com/org/b9g) (short for
 b*ikeshavin*g).
@@ -15,35 +18,37 @@ b*ikeshavin*g).
 $ npm i @b9g/crank
 ```
 
-### Hello world with the **classic** JSX transform.
-
+### Importing Crank with the **classic** JSX transform.
 ```jsx
 /** @jsx createElement */
-import {createElement} from "@b9g/crank";
+/** @jsxFrag Fragment */
+import {createElement, Fragment} from "@b9g/crank";
 import {renderer} from "@b9g/crank/dom";
+
 renderer.render(<div id="hello">Hello world</div>, document.body);
 ```
 
-### Hello world with the **automatic** JSX transform.
-
+### Importing Crank with the **automatic** JSX transform.
 ```jsx
 /** @jsxImportSource @b9g/crank */
 import {renderer} from "@b9g/crank/dom";
+
 renderer.render(<div id="hello">Hello world</div>, document.body);
 ```
 
-If you do not wish to use pragmas (`/** @jsx createElement */`, `/** @jsxImportSource @b9g/crank */`), you will likely have to configure your tools to support JSX. See below for common tools and configurations.
+If you do not wish to use the `@jsx` comment pragmas, you will likely have to configure your tools to support JSX. See below for common tools and configurations.
 
-### Hello world with the JSX template tag.
+### Importing the JSX template tag.
+
+Starting in version `0.5`, the Crank package ships a [tagged template function](/guides/jsx-template-tag) which parses the template tag with similar syntax and semantics as the JSX transform. This allows you to write Crank components in vanilla JavaScript.
 
 ```js
 import {jsx} from "@b9g/crank/standalone";
 import {renderer} from "@b9g/crank/dom";
+
 renderer.render(jsx`<div id="hello">Hello world</div>`, document.body);
 ```
 
-Starting in version `0.5`, the Crank package ships a [tagged template function](/guides/jsx-template-tag) which parses the template tag with similar syntax and semantics as the JSX transform. This allows you to write Crank components in vanilla JavaScript.
-
 ### ECMAScript Module CDNs
 Crank is also available on CDNs like [unpkg](https://unpkg.com)
 (https://unpkg.com/@b9g/crank?module) and [esm.sh](https://esm.sh)
@@ -71,7 +76,7 @@ Here’s the configuration you will need to set up automatic JSX transpilation.
 ```tsconfig.json
 {
   "compilerOptions": {
-    "jsx": "react-jsx"
+    "jsx": "react-jsx",
     "jsxImportSource": "@b9g/crank"
   }
 }
@@ -80,20 +85,116 @@ Here’s the configuration you will need to set up automatic JSX transpilation.
 The classic transform is supported as well.
 
 ```tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react",
+    "jsxFactory": "createElement",
+    "jsxFragmentFactory": "Fragment"
+  }
+}
 ```
 
-Crank is written in TypeScript. Additional information about how to type components and use Crank types are provided in the [working with TypeScript guide](/guides/working-with-typescript).
+```tsx
+import type {Context} from "@b9g/crank";
+function *Timer(this: Context) {
+  let seconds = 0;
+  const interval = setInterval(() => {
+    seconds++;
+    this.refresh();
+  }, 1000);
+  for ({} of this) {
+    yield <div>Seconds: {seconds}</div>;
+  }
 
-### Babel
-```babelrc.json
+  clearInterval(interval);
+}
 ```
 
-### ESBuild
-```bash
+Crank is written in TypeScript. Refer to [the guide on TypeScript](/guides/working-with-typescript) for more information about Crank types.
+
+### [Babel](https://babeljs.io)
+
+Babel is a popular open-source JavaScript compiler which allows you to write code with modern syntax (including JSX) and run it in environments which do not support the syntax.
+
+Here is how to get Babel to transpile JSX for Crank.
+
+Automatic transform:
+```.babelrc.json
+{
+  "plugins": [
+    "@babel/plugin-syntax-jsx",
+    [
+      "@babel/plugin-transform-react-jsx",
+      {
+        "runtime": "automatic",
+        "importSource": "@b9g/crank",
+
+        "throwIfNamespace": false,
+        "useSpread": true
+      }
+    ]
+  ]
+}
+```
+
+Classic transform:
+```.babelrc.json
+{
+  "plugins": [
+    "@babel/plugin-syntax-jsx",
+    [
+      "@babel/plugin-transform-react-jsx",
+      {
+        "runtime": "class",
+        "pragma": "createElement",
+        "pragmaFrag": "''",
+        "throwIfNamespace": false,
+        "useSpread": true
+      }
+    ]
+  ]
+}
 ```
 
 ### ESLint
+ESLint is a popular open-source tool for analyzing and detecting problems in JavaScript code.
+
+Crank provides a configuration preset for working with ESLint under the package name `eslint-plugin-crank`.
+
+```bash
+npm i eslint eslint-plugin-crank
 ```
+
+In your eslint configuration:
+
+```.eslintrc.json
+{
+  "extends": ["plugin:crank/recommended"]
+}
 ```
 
-### Shovel
+### [Astro](https://astro.build)
+
+Astro.js is a modern static site builder and framework.
+
+Crank provides an [Astro integration](https://docs.astro.build/en/guides/integrations-guide/) to enable server-side rendering and client-side hydration with Astro.
+
+```bash
+npm i astro-crank
+```
+
+In your `astro.config.mjs`.
+
+```astro.config.mjs
+import {defineConfig} from "astro/config";
+import crank from "astro-crank";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [crank()],
+});
+```
+
+## Shovel
+
+A full-stack framework is in the works for Crank. Stay tuned.

website/documents/index.md

@@ -52,7 +52,7 @@ async function Definition({word}) {
 //renderer.render(<Definition word="framework" />, document.body);
 ```
 
-Crank components work like normal JavaScript. Props can be destructured. Promises can be awaited. Updates can be iterated. State is just whatever’s held in the function scope.
+Crank components work like normal JavaScript, using standard control-flow. Props can be destructured. Promises can be awaited. Updates can be iterated. State can be held in scope.
 
 The result is a simpler developer experience, where you spend less time writing framework integrations and more time writing vanilla JavaScript.
 
@@ -200,7 +200,9 @@ function *CyclingName() {
 renderer.render(<CyclingName />, document.body);
 ```
 
-Components rerender based on explicit `refresh()` calls. This level of precision means you can be as messy as you need to be. And when you clean it up, you’ll be confident about how your code executes.
+Components rerender based on explicit `refresh()` calls. This level of precision means you can be as messy as you need to be to get the job done.
+
+Never memoize a callback ever again.
 
 ```jsx live
 import {renderer} from "@b9g/crank/dom";
@@ -283,7 +285,7 @@ async function QuoteOfTheDay() {
 renderer.render(<QuoteOfTheDay />, document.body);
 ```
 
-Async generator functions let you write components that are both async *and* stateful. Crank uses promises wherever it makes sense, and has a rich async execution model which lets you do things like racing components to display delayed fallback states.
+Async generator functions let you write components that are both async *and* stateful. Crank uses promises wherever it makes sense, and has a rich async execution model which allows you to do things like race components to display loading states.
 
 ```jsx live
 import {renderer} from "@b9g/crank/dom";