gatsbyjs · KyleAMathews · Jul 6, 2017 · Jul 5, 2017 · Jul 6, 2017 · KyleAMathews
diff --git a/docs/docs/building-with-components.md b/docs/docs/building-with-components.md
@@ -2,9 +2,192 @@
 title: Building with Components
 ---
 
-Rough outline
+## Requirements
 
-* Docs expect basic familiarity with React
-* All Gatsby site UI is built with React components.
-* Concise description of why components amazing model for building sites.
-* Perhaps link to other good articles on "Why components are amazing".
+You'll need to have basic understanding of React components.
+
+The [official tutorial](https://facebook.github.io/react/tutorial/tutorial.html) is a good place to start.
+
+## Why React components?
+
+React allows to create big complicated webapps while preserving modularity, reusabilty, and clear abstraction. React also has great devtools available for debugging the applicattion.
+
+Here you can read more about [Thinking in React](https://facebook.github.io/react/docs/thinking-in-react.html).
+
+## How does Gatsby use React Components?
+
+Everything in Gatsby is built using Components.
+
+A basic directory structure of a project looks like this:
+
+```sh
+.
+├── gatsby-config.js
+├── package.json
+└── src
+    ├── html.jsx
+    ├── pages
+    │   ├── index.jsx
+    │   └── posts
+    │       ├── 01-01-2017
+    │       │   └── index.md
+    │       ├── 01-02-2017
+    │       │   └── index.md
+    │       └── 01-03-2017
+    │           └── index.md
+    ├── templates
+    │   └── post.jsx
+    │
+    └── layouts
+        └── index.jsx
+```
+
+### Base HTML generation
+
+`src/html.jsx` is responsible for generating the base HTML document, where the react component tree is going to be mounted.
+
+Example:
+
+```jsx
+import React from 'react';
+import favicon from './favicon.png';
+
+let inlinedStyles = '';
+if (process.env.NODE_ENV === 'production') {
+  try {
+    inlinedStyles = require('!raw-loader!../public/styles.css');
+  } catch (e) {
+    console.log(e);
+  }
+}
+
+export default class HTML extends React.Component {
+  render() {
+    let css;
+    if (process.env.NODE_ENV === 'production') {
+      css = (
+        <style
+          id="gatsby-inlined-css"
+          dangerouslySetInnerHTML={{ __html: inlinedStyles }}
+        />
+      );
+    }
+    return (
+
+      <html lang="en">
+        <head>
+          <meta charSet="utf-8" />
+          <meta
+            name="viewport"
+            content="width=device-width, initial-scale=1.0"
+          />
+          {this.props.headComponents}
+          <link rel="shortcut icon" href={favicon} />
+          {css}
+        </head>
+        <body>
+          <div
+            id="___gatsby"
+            dangerouslySetInnerHTML={{ __html: this.props.body }}
+          />
+          {this.props.postBodyComponents}
+        </body>
+      </html>
+    );
+  }
+}
+```
+
+In this file you can modify the `<head>` metadata, general structure of the document and add external links.
+
+### UI Layouts
+
+`src/layouts/index.jsx` (optional) is a wrapper component for everything generated by Gatsby. You can use it to create consistent layouts between pages.
+
+Example:
+
+```jsx
+import React from 'react';
+import Navigation from '../components/Navigation/Navigation.jsx';
+
+export default class Template extends React.Component {
+
+  render() {
+    const { children } = this.props;
+    return (
+      <Navigation>
+        {children()}
+      </Navigation>
+    );
+  }
+}
+```
+
+### Page generation
+
+Components under `src/pages` are being automatically mapped to HTML files with respective paths. For example `src/pages/index.jsx` is mapped to `yoursite.com` meanwhile `src/pages/about.jsx` is `yoursite.com/about/`.
+
+Example:
+
+`src/pages/about.jsx`
+
+```jsx
+import React, { Component } from 'react';
+
+class AboutPage extends Component {
+  render() {
+    const config = this.props.data.site.siteMetadata;
+    return (
+        <div className="about-container">
+          <p>About me.</p>
+        </div>
+    );
+  }
+}
+
+export default AboutPage;
+```
+
+You may have noticed that `src/pages/posts` also contains markdown files. You can transform any file into HTML pages using [Gatsby plugins](https://www.gatsbyjs.org/docs/plugins/).
+
+### Templates
+
+`src/templates/post.jsx` (optional) is a component that queries GraphQL database for markdown information, and then generates HTML based on it.
+
+Example:
+
+```jsx
+import React from "react"
+
+class BlogPostTemplate extends React.Component {
+  render() {
+    const post = this.props.data.markdownRemark
+
+    return (
+      <div>
+        <h1>{post.frontmatter.title}</h1>
+        <div dangerouslySetInnerHTML={{ __html: post.html }} />
+      </div>
+    )
+  }
+}
+
+export default BlogPostTemplate
+
+export const pageQuery = graphql`
+query BlogPostBySlug($slug: String!) {
+  markdownRemark(fields: { slug: { eq: $slug }}) {
+    html
+    frontmatter {
+      title
+    }
+  }
+}
+`
+```
+
+Please note, that for this to work, you'll also need to configure:
+
+* Gatsby plugins using `gatsby-config.js`
+* Gatsby GraphQL database generation using `gatsby-node.js`
+* Gatsby page generation using `gatsby-node.js`