Merge pull request #188 from facebook/docs-refactor

Look ma, new docs!

docs/_config.yml

@@ -1,17 +1,54 @@
----
-markdown: redcarpet
-name: React
-description: A JavaScript library for building user interfaces
-redcarpet:
-  extensions:
-  - fenced_code_blocks
-react_version: 0.3.2
-pygments: true
-exclude:
+--- 
+baseurl: /react
+url: http://facebook.github.io
+permalink: /blog/:year/:month/:day/:title.html
+exclude: 
 - Gemfile
 - Gemfile.lock
 - README.md
 - Rakefile
-url: http://facebook.github.io
-baseurl: /react
-permalink: /blog/:year/:month/:day/:title.html
+redcarpet: 
+  extensions: 
+  - fenced_code_blocks
+pygments: true
+name: React
+markdown: redcarpet
+react_version: 0.4.0a
+description: A JavaScript library for building user interfaces
+relative_permalinks: true
+
+nav_docs_sections:
+- title: Quick Start
+  items:
+  - id: getting-started
+    title: Getting Started
+  - id: tutorial
+    title: Tutorial
+- title: Guides
+  items:
+    - id: why-react
+      title: Why React?
+    - id: displaying-data
+      title: Displaying Data
+      subitems:
+      - id: jsx-in-depth
+        title: JSX in Depth
+      - id: jsx-gotchas
+        title: JSX Gotchas
+    - id: interactivity-and-dynamic-uis
+      title: Interactivity and Dynamic UIs
+    - id: multiple-components
+      title: Multiple Components
+    - id: reusable-components
+      title: Reusable Components
+    - id: forms
+      title: Forms
+    - id: working-with-the-browser
+      title: Working With the Browser
+      subitems:
+      - id: more-about-refs
+        title: More About Refs
+    - id: tooling-integration
+      title: Tooling integration
+    - id: reference
+      title: Reference

docs/_css/react.scss

@@ -206,6 +206,9 @@ li {
     list-style: none;
     margin: 0;
   }
+  ul ul {
+    margin-left: 20px;
+  }
   li {
     margin: 0;
   }

docs/_includes/nav_docs.html

@@ -1,31 +1,27 @@
 <div class="nav-docs">
-  <div class="nav-docs-section">
-    <h3>Getting started</h3>
-    <ul>
-      <li><a href="/react/docs/getting-started.html"{% if page.id == 'docs-getting-started' %} class="active"{% endif %}>Getting Started</a></li>
-      <li><a href="/react/docs/tutorial.html"{% if page.id == 'docs-tutorial' %} class="active"{% endif %}>Tutorial</a></li>
-      <li><a href="/react/docs/common-questions.html"{% if page.id == 'docs-common-questions' %} class="active"{% endif %}>Common Questions</a></li>
-    </ul>
-  </div>
-
-  <div class="nav-docs-section">
-    <h3>Reference</h3>
-    <ul>
-      <li><a href="/react/docs/syntax.html"{% if page.id == 'docs-syntax' %} class="active"{% endif %}>JSX Syntax</a></li>
-      <li><a href="/react/docs/component-basics.html"{% if page.id == 'docs-component-basics' %} class="active"{% endif %}>Component Basics</a></li>
-      <li><a href="/react/docs/component-data.html"{% if page.id == 'docs-component-data' %} class="active"{% endif %}>Component Data</a></li>
-      <li><a href="/react/docs/component-lifecycle.html"{% if page.id == 'docs-component-lifecycle' %} class="active"{% endif %}>Component Lifecycle</a></li>
-      <li><a href="/react/docs/event-handling.html"{% if page.id == 'docs-event-handling' %} class="active"{% endif %}>Event Handling</a></li>
-      <li><a href="/react/docs/advanced-components.html"{% if page.id == 'docs-advanced-components' %} class="active"{% endif %}>Advanced Components</a></li>
-      <li><a href="/react/docs/mixins.html"{% if page.id == 'docs-mixins' %} class="active"{% endif %}>Mixins</a></li>
-      <li><a href="/react/docs/api.html"{% if page.id == 'docs-api' %} class="active"{% endif %}>API</a></li>
-    </ul>
-  </div>
-
-  <div class="nav-docs-section">
-    <h3>Appendix</h3>
-    <ul>
-      <li><a href="/react/docs/jsx-is-not-html.html"{% if page.id == 'docs-jsx-is-not-html' %} class="active"{% endif %}>JSX is not HTML</a></li>
-    </ul>
-  </div>
+  {% for section in site.nav_docs_sections %}
+    <div class="nav-docs-section">
+      <h3>{{ section.title }}</h3>
+      <ul>
+        {% for item in section.items %}
+          <li>
+            <a href="/react/docs/{{ item.id }}.html"{% if page.id == item.id %} class="active"{% endif %}>
+              {{ item.title }}
+            </a>
+            {% if item.subitems %}
+              <ul>
+                {% for subitem in item.subitems %}
+                  <li>
+                    <a href="/react/docs/{{ subitem.id }}.html"{% if page.id == subitem.id %} class="active"{% endif %}>
+                      {{ subitem.title }}
+                    </a>
+                  </li>
+                {% endfor %}
+              </ul>
+            {% endif %}
+          </li>
+        {% endfor %}
+      </ul>
+    </div>
+  {% endfor %}
 </div>

docs/_js/examples/markdown.js

@@ -11,9 +11,9 @@ var MarkdownEditor = React.createClass({\n\
   getInitialState: function() {\n\
     return {value: 'Type some *markdown* here!'};\n\
   },\n\
-  handleInput: React.autoBind(function() {\n\
+  handleInput: function() {\n\
     this.setState({value: this.refs.textarea.getDOMNode().value});\n\
-  }),\n\
+  },\n\
   render: function() {\n\
     return (\n\
       <div className=\"MarkdownEditor\">\n\

docs/_js/examples/timer.js

@@ -7,9 +7,9 @@ var Timer = React.createClass({\n\
   getInitialState: function() {\n\
     return {secondsElapsed: 0};\n\
   },\n\
-  tick: React.autoBind(function() {\n\
+  tick: function() {\n\
     this.setState({secondsElapsed: this.state.secondsElapsed + 1});\n\
-  }),\n\
+  },\n\
   componentDidMount: function() {\n\
     setInterval(this.tick, 1000);\n\
   },\n\

docs/docs/01-why-react.md

@@ -0,0 +1,30 @@
+---
+id: why-react
+title: Why React?
+layout: docs
+permalink: why-react.html
+next: displaying-data.html
+---
+React is a JavaScript library for creating user interfaces by Facebook and Instagram. Many people choose to think of React as the **V** in **[MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller)**.
+
+We built React to solve one problem: **building large applications with data that changes over time**. To do this, React uses two main ideas.
+
+### Simple
+
+Simply express how your app should look at any given point in time, and React will automatically manage all UI updates when your underlying data changes.
+
+### Declarative
+
+When the data changes, React conceptually hits the "refresh" button, and knows to only update the changed parts.
+
+## Build Composable Components
+
+React is all about building reusable components. In fact, with React the *only* thing you do is build components. Since they're so encapsulated, components make code reuse, testing, and separation of concerns easy.
+
+## Give It Five Minutes
+
+React challenges a lot of conventional wisdom, and at first glance some of the ideas may seem crazy. [Give it five minutes](http://37signals.com/svn/posts/3124-give-it-five-minutes) while reading this guide; those crazy ideas have worked for building thousands of components both inside and outside of Facebook and Instagram.
+
+## Learn More
+
+You can learn more about our motivations behind building React in [this blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html).

docs/docs/02-displaying-data.md

@@ -0,0 +1,91 @@
+---
+id: displaying-data
+title: Displaying Data
+layout: docs
+permalink: displaying-data.html
+prev: why-react.html
+next: jsx-in-depth.html
+---
+
+The most basic thing you can do with a UI is display some data. React makes it easy to display data and automatically keeps the interface up-to-date when the data changes.
+
+
+## Getting Started
+
+Let's look at a really simple example. Create a `hello-react.html` file with the following code:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Hello React</title>
+    <script src="http://fb.me/react-{{site.react_version}}.min.js"></script>
+    <script src="http://fb.me/JSXTransformer-{{site.react_version}}.js"></script>
+  </head>
+  <body>
+    <div id="example"></div>
+    <script type="text/jsx">
+
+      // ** Your code goes here! **
+
+    </script>
+  </body>
+</html>
+```
+
+For the rest of the documentation, we'll just focus on the JavaScript code and assume it's inserted into a template like the one above. Replace the placeholder comment above with the following JS:
+
+```javascript
+/** @jsx React.DOM */
+
+var HelloWorld = React.createClass({
+  render: function() {
+    return (
+      <p>
+        Hello, <input type="text" placeholder="Your name here" />!
+        It is {this.props.date.toTimeString()}
+      </p>
+    );
+  }
+});
+
+setInterval(function() {
+  React.renderComponent(
+    <HelloWorld date={new Date()} />,
+    document.getElementById('example')
+  );
+}, 500);
+```
+
+
+## Reactive Updates
+
+Open `hello-react.html` in a web browser and type your name into the text field. Notice that React is only changing the time string in the UI — any input you put in the text field remains, even though you haven't written any code to manage this behavior. React figures it out for you and does the right thing.
+
+The way we are able to figure this out is that React does not manipulate the DOM unless it needs to. **It uses a fast, internal mock DOM to perform diffs and computes the most efficient DOM mutation for you.**
+
+The inputs to this component are called `props` — short for "properties". They're passed as attributes in JSX syntax. You should think of these as immutable within the component, that is, **never write to `this.props`**.
+
+
+## Components are Just Like Functions
+
+React components are very simple. You can think of them as simple function that take in `props` and `state` (discussed later) and render HTML. Because they're so simple, it makes them very easy to reason about.
+
+> Note:
+>
+> **One limitation**: React components can only render a single root node. If you want to return multiple nodes they *must* be wrapped in a single root.
+
+
+## JSX Syntax
+
+We strongly believe that components are the right way to separate concerns rather than "templates" and "display logic." We think that markup and the code that generates it are intimately tied together. Additionally, display logic is often very complex and using template languages to express it becomes cumbersome.
+
+We've found that the best solution for this problem is to generate markup directly from the JavaScript code such that you can use all of the expressive power of a real programming language to build UIs. In order to make this easier, we've added a very simple, **optional** HTML-like syntax for the function calls that generate markup called JSX.
+
+**JSX lets you write JavaScript function calls with HTML syntax.** To generate a link in React using pure JavaScript you'd write: `React.DOM.a({href: 'http://facebook.github.io/react/'}, 'Hello React!')`. With JSX this becomes `<a href="http://facebook.github.io/react/">Hello React!</a>`. We've found this has made building React apps easier and designers tend to prefer the syntax, but everyone has their own workflow, so **JSX is not required to use React.**
+
+JSX is very small; the "hello, world" example above uses every feature of JSX. To learn more about it, see [JSX in depth](./02.1-jsx-in-depth.html). Or see the transform in action in [our live JSX compiler](/react/jsx-compiler.html).
+
+JSX is similar to HTML, but not exactly the same. See [JSX gotchas](./02.2-jsx-gotchas.html) for some key differences.
+
+The easiest way to get started with JSX is to use the in-browser `JSXTransformer`. We strongly recommend that you don't use this in production. You can precompile your code using our command-line [react-tools](http://npmjs.org/package/react-tools) package.