bikeshaving · dfabulich · May 1, 2020
diff --git a/website/blog/2020-04-15-introducing-crank.md b/website/blog/2020-04-15-introducing-crank.md
@@ -86,4 +86,4 @@ By combining these relatively old, almost boring technologies with JSX syntax, I
 
 And again, I sincerely apologize for creating yet another framework in an already crowded space, but I hope, if you’ve read this far, you understand why I did so, namely, because I thought React was dropping the ball in terms of its newest APIs, because I still wanted to use JSX, and because of the sudden realization that we could be doing so much more with the different function syntaxes available to us in JavaScript.
 
-If any of this interests you, if you want to continue to use JSX over template languages, if you’re tired of debugging hooks, if you want to use promises in your components *today*, if you’re looking for a framework which has, arguably, the most “just JavaScript” story for reactivity, I encourage you to check out Crank. You can read [the documentation](/guides/getting-started) or check out the [TodoMVC example](https://codesandbox.io/s/crank-todomvc-k6s0x) that made me tear up a little. Crank is still in its early days, and there’s a lot of work to be done before it can be considered a full-fledged framework, but I think the ideas behind it are sound and I’ve thoroughly enjoyed designing it. I can’t wait to see what people build with Crank.
+If any of this interests you, if you want to continue to use JSX over template languages, if you’re tired of debugging hooks, if you want to use promises in your components *today*, if you’re looking for a framework which has, arguably, the most “just JavaScript” story for reactivity, I encourage you to check out Crank. You can read [the documentation](/guides/learn-by-example) or check out the [TodoMVC example](https://codesandbox.io/s/crank-todomvc-k6s0x) that made me tear up a little. Crank is still in its early days, and there’s a lot of work to be done before it can be considered a full-fledged framework, but I think the ideas behind it are sound and I’ve thoroughly enjoyed designing it. I can’t wait to see what people build with Crank.
diff --git a/website/guides/00-getting-started.md b/website/guides/00-getting-started.md
@@ -0,0 +1,152 @@
+---
+title: Installation
+---
+
+Crank is available on [NPM](https://npmjs.org/@bikeshaving/crank) and on the unpkg CDN, in the ESModule and CommonJS formats.
+
+## In the browser (no build tool)
+
+You can use Crank directly in your browser, without a build step, like this. 
+
+```html
+<!-- Don't do this in production! -->
+<script src="https://unpkg.com/babel-standalone/babel.min.js"></script>
+<script type="module">
+  import {createElement} from "https://unpkg.com/@bikeshaving/crank?module";
+  import {renderer} from "https://unpkg.com/@bikeshaving/crank/dom?module";
+  window.createElement = createElement;
+  window.renderer = renderer;
+</script>
+<script type="text/babel">
+  /** @jsx createElement */
+  renderer.render(<div id="hello">Hello world</div>, document.body);
+</script>
+```
+
+(Don't do this in production! Transpiling JSX and importing Crank in the user's browser at runtime hurts performance. It's better to transpile JSX and bundle Crank ahead of time, during a build step on your own computer. But this is an easy way to try out Crank.)
+
+## Use JSX with Babel and Parcel
+
+Crank is designed to be used with a JSX transpiler. In this example, we'll set up [Babel](https://babeljs.io/) and [Parcel](https://parceljs.org/).
+
+```shell
+$ npm install @bikeshaving/crank
+$ npm install --save-dev parcel-bundler
+```
+
+Create a `.babelrc` file like this:
+
+```
+{
+  "presets": [
+    "@babel/preset-react"
+  ]
+}
+```
+
+Create an `index.html` file like this:
+
+```html
+<html>
+<body>
+<script src="src/index.js"></script>
+</body>
+</html>
+```
+
+Create a `src` folder containing `index.js` like this:
+
+```jsx
+/** @jsx createElement */
+import {createElement} from "@bikeshaving/crank";
+import {renderer} from "@bikeshaving/crank/dom";
+
+function Greeting({name = "World"}) {
+  return (
+    <div>Hello {name}</div>
+  );
+}
+
+renderer.render(<Greeting />, document.body);
+```
+
+Add these scripts to the `scripts` section of your `package.json`.
+
+```js
+  "scripts": {
+    "start": "parcel index.html --open",
+    "build": "parcel build index.html"
+  },
+```
+
+Then you can `npm run start` to view your app in the browser.
+
+[Try on CodeSandbox](https://codesandbox.io/s/a-simple-crank-component-mhciu)
+
+### Use JSX in Node.js for Server-Side Rendering
+
+In Node, we need to `import` Crank in CommonJS (`cjs`) format, and use the `html` renderer to generate HTML as a string.
+
+After setting up JSX according to the steps above, create this file as `ssr.js`
+
+```js
+/** @jsx createElement */
+import {createElement} from "@bikeshaving/crank/cjs/index.js";
+import {renderer} from "@bikeshaving/crank/cjs/html.js";
+
+function Greeting({name = "World"}) {
+  return (
+    <div>Hello {name}</div>
+  );
+}
+
+console.log(renderer.render(<Greeting />));
+```
+
+```shell
+$ npx parcel build ssr.js
+$ node dist/ssr.js
+<div>Hello World</div>
+```
+
+## Alternative: Use HTM instead of JSX
+
+If you'd like to avoid transpiling JSX, you can use [HTM](https://github.com/developit/htm) instead. HTM is less beautiful than JSX, but it's easier to set up.
+
+```html
+<script type="module">
+  import {createElement} from "https://unpkg.com/@bikeshaving/crank?module";
+  import {renderer} from "https://unpkg.com/@bikeshaving/crank/dom?module";
+  import htm from 'https://unpkg.com/htm?module'
+  const h = htm.bind(createElement);
+
+  function Greeting({name = "World"}) {
+    return h`
+      <div>Hello ${name}</div>
+    `;
+  }
+
+  renderer.render(h`<${Greeting} />`, document.body);
+</script>
+```
+
+Or, in Node:
+
+```shell
+$ npm install htm @bikeshaving/crank
+```
+
+```js
+const {createElement} = require("@bikeshaving/crank/cjs/index.js");
+const {renderer} = require("@bikeshaving/crank/cjs/html.js");
+const h = require("htm").bind(createElement);
+
+function Greeting({name = "World"}) {
+  return h`
+    <div>Hello ${name}</div>
+  `;
+}
+
+console.log(renderer.render(h`<${Greeting} />`));
+```
+
diff --git a/website/guides/01-getting-started.md → website/guides/01-learn-by-example.md b/website/guides/01-getting-started.md → website/guides/01-learn-by-example.md
@@ -1,34 +1,8 @@
 ---
-title: Getting Started
+title: Learn by Example
 ---
 
-## Installation
-Crank is available on [NPM](https://npmjs.org/@bikeshaving/crank) in the ESModule and CommonJS formats.
-
-```shell
-$ npm install @bikeshaving/crank
-```
-
-```jsx
-/** @jsx createElement */
-import {createElement} from "@bikeshaving/crank";
-import {renderer} from "@bikeshaving/crank/dom";
-
-renderer.render(<div id="hello">Hello world</div>, document.body);
-```
-
-If your environment does not support ESModules (you’ll probably see a message like `SyntaxError: Unexpected token export`), you can import the CommonJS versions of the library under the `cjs` directory.
-
-```jsx
-/** @jsx createElement */
-import {createElement} from "@bikeshaving/crank/cjs";
-import {renderer} from "@bikeshaving/crank/cjs/dom";
-
-renderer.render(<div id="hello">Hello world</div>, document.body);
-```
-
-## Key Examples
-### A Simple Component
+## A Simple Component
 ```jsx
 /** @jsx createElement */
 import {createElement} from "@bikeshaving/crank";
@@ -45,7 +19,7 @@ renderer.render(<Greeting />, document.body);
 
 [Try on CodeSandbox](https://codesandbox.io/s/a-simple-crank-component-mhciu)
 
-### A Stateful Component
+## A Stateful Component
 ```jsx
 /** @jsx createElement */
 import {createElement} from "@bikeshaving/crank";
@@ -71,7 +45,7 @@ renderer.render(<Timer />, document.body);
 
 [Try on CodeSandbox](https://codesandbox.io/s/a-stateful-crank-component-hh8zx)
 
-### An Async Component
+## An Async Component
 ```jsx
 /** @jsx createElement */
 import {createElement} from "@bikeshaving/crank";
@@ -92,7 +66,7 @@ renderer.render(<QuoteOfTheDay />, document.body);
 
 [Try on CodeSandbox](https://codesandbox.io/s/an-async-crank-component-ru02q)
 
-### A Loading Component
+## A Loading Component
 ```jsx
 /** @jsx createElement */
 import {createElement, Fragment} from "@bikeshaving/crank";