react templates guide

website/site/content/docs/creating-a-template-compiler.md

@@ -1,6 +1,6 @@
 ---
 title: Creating a Template Compiler
-position: 40
+weight: 40
 menu:
   docs:
     parent: guides

website/site/content/docs/custom-previews.md

@@ -1,12 +1,15 @@
 ---
-title: Custom Previews
-position: 50
+title: Custom Preview
+weight: 50
+menu:
+  docs:
+    parent: guides
 ---
 
 # Customizing the Preview Pane
 
-The preview pane displays an HTML preview of the content you're editing, and can be customized to
-display content identical to your production site using templates and CSS.
+The preview pane displays an HTML "preview" of the content you're editing, and can be customized to
+match your production site using templates and CSS.
 
 ## Preview Templates
 
@@ -28,7 +31,8 @@ fields:
   - { name: text, label: Text, widget: text }
 ```
 
-A preview template displaying these fields might look like this:
+We can access these fields by name in the preview template. A template displaying these fields might
+look like this:
 
 ```handlebars
 <div>
@@ -42,9 +46,7 @@ You can add styles and classes as necessary to make the preview match your produ
 
 ### Registering Templates
 
-Once you have a template, you'll need to register it to be used with a collection. We're
-using a handlebars template, so we'll only need to provide a name for the template and the template
-itself.
+Once you have a template, you'll need to register it:
 
 ```js
 // You can pull in your template in a number of ways, but we'll go with an
@@ -59,13 +61,14 @@ const template = `
 CMS.registerPreviewTemplate('blog', template)
 ```
 
+Notice the first argument, "blog" - that's the name we're registering the template under.
 Registering a template may require other arguments depending on your template compiler. For more
 information on `registerPreviewTemplate`, check out the [API docs](#), as well as the docs for your
 template compiler.
 
-Now that you've registered your template, you'll want to add use it in one or more collections. This
-happens in your CMS configuration file via the `preview_template` key for a collection. Applying the
-"blog" template we just registered to a collection named "posts" would look like this:
+Now that you've registered your template, you'll want to apply it to one or more collections. You
+can do this in your CMS configuration file via the `preview_template` key for each collection.
+Applying our "blog" template to a collection named "posts" would look like this:
 
 ```yaml
 collections:
@@ -76,11 +79,9 @@ collections:
 
 ### Using Field Previews
 
-When a preview template accesses a field value, it receives the raw value itself. This is the same
-value that is output when an entry is saved, and is produced by the field widget's [control
-component](#).  Many widgets also have a [preview component](#) that outputs an HTML representation of
-the field's value specifically for use in the preview pane. This is referred to as the Field
-Preview.
+When a preview template accesses a field value, it receives the raw value itself. Many widgets also
+have a [preview component](#) that outputs an HTML representation of the field's value specifically
+for use in the preview pane. This is referred to as the Field Preview.
 
 We'll use a Markdown field to demonstrate. Here's a YAML file with a couple of fields:
 
@@ -112,7 +113,7 @@ receive:
 We don't want to display raw markdown in the preview pane like this - we want the HTML
 representation of the markdown instead, which is exactly what the Markdown widget's preview
 component provides. This may differ for some template compilers, but previews are generally
-accessible through the `__preview` object by prepending "__preview" to your key.
+accessible through the `__preview` object.
 
 In other words, take the key you would normally access your value with, and put "__preview." at the
 beginning. In our case, `description` becomes `__preview.description`.

website/site/content/docs/jsx-in-the-browser.md

@@ -0,0 +1,25 @@
+---
+title: JSX in the Browser
+weight: 100
+menu:
+  docs:
+    parent: start
+---
+
+# JSX in the Browser
+
+Because Netlify CMS uses React, and React is most often used with [JSX](#), customizing the CMS
+generally involves a build system to transform the JSX into JavaScript. If you prefer to write JSX
+(say for custom widgets or preview templates) without using a build system, you can do so using
+[babel-standalone](https://github.com/babel/babel/tree/master/packages/babel-standalone):
+
+```html
+  <script src="https://unpkg.com/react@16/umd/react.development.js"></script>
+  <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+  <script type="text/babel">
+    const PreviewTemplate = () => <h1>Totally works.</h1>
+  </script>
+```
+
+Note the use of `react.development.js` - this is ideal during development for useful error messages.
+When you're ready for production, use `react.production.js`.

website/site/content/docs/react-templates.md

@@ -0,0 +1,76 @@
+---
+title: React Preview Templates
+weight: 60
+menu:
+  docs:
+    parent: guides
+---
+
+# React Preview Templates
+
+React is the default "template language" for previews. Each preview template is a component that
+accepts the entry and other data as `props`. For React based static site generators, like Gatsby and
+React Static, production site template components can often be reused as Netlify CMS preview
+components.
+
+**Unfamiliar with React?** You may want to [brush
+up](https://reactjs.org/docs/hello-world.html) on it before proceeding.
+
+**No build system?** If you want to write [JSX](#) as we do in the examples below, but are not using a
+build system, check out the [JSX in the browser](#) guide for tips.
+
+
+## Props
+
+The following props are available to React preview template components:
+
+### `props.entry`
+
+#### `props.entry.fields`
+
+An object containing all configured fields for the current entry, including nested
+fields. Each field object will contain up to three properties:
+
+**`value`:** the raw field value\
+**`preview`:** _(optional)_ the HTML field preview\
+**`data`:** _(optional)_ secondary field data\
+
+```js
+const PostPreview = (props) => {
+  const fields = props.entry.fields;
+  return (
+    <div>
+      <img src={fields.cover.data.src}/>
+      <h1>{fields.title.value}</h1>
+      <div>{fields.author.name.value}</div>
+      <div>{fields.date.value}</div>
+      <div>{fields.body.preview}</div>
+    </div>
+  )
+}
+```
+
+### `props.entry.collection`
+
+The name of the collection containing the current entry.
+
+### `props.collections`
+
+`props.collections` is an object containing all collections and their entries. The entry objects
+contain the same `fields` property as documented under [`props.fields`](#).
+
+```js
+const PostPreview = (props) => {
+  const fields = props.entry.fields;
+  const collections = props.collections;
+  return (
+    <div>
+      <h1>{fields.title.value}</h1>
+      <div>{collections.authors.fields}
+      <div>{fields.author.name.value}</div>
+      <div>{fields.date.value}</div>
+      <div>{fields.body.preview}</div>
+    </div>
+  )
+}
+```