website refactoring

clean up optimization docs
rearrange sections in nav bar
add layout api sizing Q to FAQ
add corner rounding to Optimizations + check back soon tags for methods to be released in 2.0
add layoutSpecs
Containers overview -> node containers
Node overview -> node subclasses
remove ASTextCellNode

_data/nav_docs.yml

@@ -21,7 +21,6 @@
   items:
   - display-node
   - cell-node
-  - text-cell-node
   - control-node
   - button-node
   - text-node
@@ -34,17 +33,22 @@
   - scroll-node
 - title: Layout
   items:
-- title: Optimizations
+  - automatic-layout-containers
+- title: Advanced Layout
   items:
-  - layer-backing
-  - synchronous-concurrency
-  - subtree-rasterization
+  - layout-api-sizing
 - title: Conveniences
   items:
   - hit-test-slop
   - batch-fetching-api
   - image-modification-block
   - placeholder-fade-duration
+- title: Optimizations
+  items:
+  - layer-backing
+  - subtree-rasterization
+  - synchronous-concurrency
+  - corner-rounding
 - title: Tools
   items:
   - debug-tool-hit-test-visualization

_docs/automatic-layout-containers.md

@@ -1,24 +1,146 @@
 ---
-title: Layout Containers
+title: LayoutSpecs
 layout: docs
 permalink: /docs/automatic-layout-containers.html
 prevPage: automatic-layout-basics.html
 nextPage: automatic-layout-examples.html 
 ---
 
-AsyncDisplayKit includes a library of components that can be composed to declaratively specify a layout. The following LayoutSpecs allow you to have multiple children:
+AsyncDisplayKit includes a library of `layoutSpec` components that can be composed to declaratively specify a layout. The **child(ren) of a layoutSpec may be a node, a layoutSpec or a combination of the two types.**  
 
-* **ASStackLayoutSpec** is based on a simplified version of CSS flexbox. It allows you to stack components vertically or horizontally and specify how they should be flexed and aligned to fit in the available space. 
-* **ASStaticLayoutSpec** allows positioning children at fixed offsets.
+Both nodes and layoutSpecs conform to the `<ASLayoutable>` protocol.  Any `ASLayoutable` object may be the child of a layoutSpec. <a href = "automatic-layout-containers.html#layoutable-properties">ASLayoutable properties</a> may be applied to ASLayoutable objects to create complex UIs. 
 
-The following layoutSpecs allow you to layout a single children: 
 
-* **ASLayoutSpec** can be used as a spacer if it contains no children
-* **ASInsetLayoutSpec** applies an inset margin around a component.
-* **ASBackgroundLayoutSpec** lays out a component, stretching another component behind it as a backdrop.
-* **ASOverlayLayoutSpec** lays out a component, stretching another component on top of it as an overlay.
-* **ASCenterLayoutSpec** centers a component in the available space.
-* **ASRatioLayoutSpec** lays out a component at a fixed aspect ratio. Great for images, gifs and videos.
-* **ASRelativeLayoutSpec** lays out a component and positions it within the layout bounds according to vertical and horizontal positional specifiers. Similar to the “9-part” image areas, a child can be positioned at any of the 4 corners, or the middle of any of the 4 edges, as well as the center.
+### Single Child layoutSpecs
+
+<table style="width:100%"  class = "paddingBetweenCols">
+  <tr>
+    <th>LayoutSpec</th>
+    <th>Description</th> 
+  </tr>
+  <tr>
+    <td><b><code>ASInsetLayoutSpec</code></b></td>
+    <td>applies an inset margin around a component. </td> 
+  </tr>
+  <tr>
+    <td><b><code>ASRatioLayoutSpec</code></b></td>
+    <td>lays out a component at a fixed aspect ratio (which can be scaled). Great for images, gifs and videos. </td> 
+  </tr>
+  <tr>
+    <td><b><code>ASOverlayLayoutSpec</code></b></td>
+    <td>lays out a component, stretching another component on top of it as an overlay. <b>The order in which subnodes are added matter for this layoutSpec</b>.</td> 
+  </tr>
+  <tr>
+    <td><b><code>ASBackgroundLayoutSpec</code></b></td>
+    <td>lays out a component, stretching another component behind it as a backdrop. <b>The order in which subnodes are added matter for this layoutSpec</b>.</td> 
+  </tr>
+  <tr>
+    <td><b><code>ASCenterLayoutSpec</code></b></td>
+    <td>centers a component in the available space. </td> 
+  </tr>
+  <tr>
+    <td><b><code>ASRelativeLayoutSpec</code></b></td>
+    <td>lays out a component and positions it within the layout bounds according to vertical and horizontal positional specifiers. Similar to the “9-part” image areas, a child can be positioned at any of the 4 corners, or the middle of any of the 4 edges, as well as the center. </td> 
+  </tr>
+  <tr>
+    <td><b><code>ASLayoutSpec</code></b></td>
+    <td>can be used as a spacer if it contains no child.</td> 
+  </tr>
+</table> 
+
+### Multiple Child(ren) layoutSpecs
+
+The following layoutSpecs may contain one or more children. 
+
+<table style="width:100%" class = "paddingBetweenCols">
+  <tr>
+    <th>LayoutSpec</th>
+    <th>Description</th> 
+  </tr>
+  <tr>
+    <td><b><code>ASStackLayoutSpec</code></b></td>
+    <td>is based on a simplified version of CSS flexbox. It allows you to stack components vertically or horizontally and specify how they should be flexed and aligned to fit in the available space.</td> 
+  </tr>
+  <tr>
+    <td><b><code>ASStackLayoutSpec</code></b></td>
+    <td>is based on a simplified version of CSS flexbox. It allows you to stack components vertically or horizontally and specify how they should be flexed and aligned to fit in the available space. </td> 
+  </tr>
+  <tr>
+    <td><b><code>ASStaticLayoutSpec</code></b></td>
+    <td>allows positioning children at fixed offsets. </td> 
+  </tr>
+</table>
+
+# ASLayoutable Properties
+
+The following properties can be applied to both nodes _and_ layoutSpecs; both conform to the <ASLayoutable> protocol. 
+
+### ASStackLayoutable Properties
+
+The following properties will only apply to a child wrapped in an **stack** layoutSpec.
+
+<table style="width:100%"  class = "paddingBetweenCols">
+  <tr>
+    <th>Property</th>
+    <th>Description</th> 
+  </tr>
+  <tr>
+    <td><b><code>CGFloat .spacingBefore</code></b></td>
+    <td>Additional space to place before this object in the stacking direction.</td> 
+  </tr>
+  <tr>
+    <td><b><code>CGFloat .spacingAfter</code></b></td>
+    <td>Additional space to place after this object in the stacking direction.</td> 
+  </tr>
+  <tr>
+    <td><b><code>BOOL .flexGrow</code></b></td>
+    <td>If the sum of childrens' stack dimensions is less than the minimum size, should this object grow? Used when attached to a stack layout.</td> 
+  </tr>
+  <tr>
+    <td><b><code>BOOL .flexShrink</code></b></td>
+    <td>If the sum of childrens' stack dimensions is greater than the maximum size, should this object shrink? Used when attached to a stack layout.</td> 
+  </tr>
+  <tr>
+    <td><b><code>ASRelativeDimension .flexBasis</code></b></td>
+    <td>Specifies the initial size for this object, in the stack dimension (horizontal or vertical), before the flexGrow or flexShrink properties are applied and the remaining space is distributed.</td> 
+  </tr>
+  <tr>
+    <td><b><code>ASStackLayoutAlignSelf alignSelf</code></b></td>
+    <td>Orientation of the object along cross axis, overriding alignItems. Used when attached to a stack layout.</td> 
+  </tr>
+  <tr>
+    <td><b><code>CGFloat .ascender</code></b></td>
+    <td>Used for baseline alignment. The distance from the top of the object to its baseline./td> 
+  </tr>
+  <tr>
+    <td><b><code>CGFloat .descender</code></b></td>
+    <td>Used for baseline alignment. The distance from the baseline of the object to its bottom.</td> 
+  </tr>
+</table> 
+
+### ASStaticLayoutable Properties
+
+The following properties will only apply to a child wrapped in an **static** layoutSpec.
+
+<table style="width:100%"  class = "paddingBetweenCols">
+  <tr>
+    <th>Property</th>
+    <th>Description</th> 
+  </tr>
+  <tr>
+    <td><b><code>.sizeRange</code></b></td>
+    <td>If specified, the child's size is restricted according to this `ASRelativeSizeRange`. Percentages are resolved relative to the static layout spec.</td> 
+  </tr>
+  <tr>
+    <td><b><code>.layoutPosition</code></b></td>
+    <td>The `CGPoint` position of this object within its parent spec.</td> 
+  </tr>
+</table>
+
+### Best Practices
+
+<ul>
+  <li>don't wrap everything in a staticLayoutSpec</li>
+  <li>avoid using preferred frame size for everything - won't respond nicely to device rotation or device sizing differences</li>
+</ul>
 
-##Strategy

_docs/cell-node.md

@@ -140,4 +140,3 @@ With this property set to `YES`, the main thread will be blocked until display h
 <div class = "note">
 Using this option does not eliminate all of the performance advantages of AsyncDisplayKit. Normally, a cell has been preloading and is almost done when it reaches the screen, so the blocking time is very short.  Even if the rangeTuningParameters are set to 0 this option outperforms UIKit.  While the main thread is waiting, subnode display executes concurrently.
 </div>
-

_docs/containers-overview.md

@@ -1,5 +1,5 @@
 ---
-title: Containers Overview
+title: Node Containers
 layout: docs
 permalink: /docs/containers-overview.html
 prevPage: layout-engine.html

_docs/corner-rounding.md

@@ -65,7 +65,9 @@ A key limitation of precomposited corners is that the corners must only touch on
 
 Note that AsyncDisplayKit nodes have a special optimization of `.cornerRadius` that automatically implements precomposited corners **only when using** `.shouldRasterizeDescendants`.  It's important to think carefully before you enable rasterization, so don't use this option without first reading all about the <a href = "subtree-rasterization.html">concept</a>.
 
-Finally, if you're looking for a simple, flat-color rounded rectangle or circle, AsyncDisplayKit offers a variety of conveniences to provide this.  See `UIImage+ASConveniences.h` for methods to create flat-colored, rounded-corner resizable images using precomposited corners (both alpha and opaque are supported). 
+<div class = "note">
+If you're looking for a simple, flat-color rounded rectangle or circle, AsyncDisplayKit offers a variety of conveniences to provide this.  See `UIImage+ASConveniences.h` for methods to create flat-colored, rounded-corner resizable images using precomposited corners (both alpha and opaque are supported). These are great for use as placeholders for image nodes or backgrounds for ASButtonNode. <b>More precomposited corner methods will be released with AsyncDisplayKit 2.0 release</b>.
+</div>
 
 ### Clip Corner
 
@@ -80,6 +82,10 @@ Clip corners applies to two main types of corner rounding situations:
 <li>Rounded corners on top of a stationary texture or photo background.  The photo clip corner method is tricky, but useful!</li>
 </ul>
 
+<div class = "note">
+<b>Check back soon! Clip corner methods may be released in AsyncDisplayKit 2.0 release</b>.
+</div>
+
 ##Is it ever okay to use CALayer's .cornerRadius property?
 
 There are a few, quite rare cases in which it is appropriate to use `.cornerRadius.` These include when there is dynamic content moving _both_ through the inside and underneath the corner.  For certain animations, this is impossible to avoid.  However, in many cases, it is easy to adjust your design to eliminate one of the sources of movement.  One such case was discussed in the section on corner movement.

_docs/debug-tool-hit-test-visualization.md

@@ -2,7 +2,7 @@
 title: Hit Test Visualization
 layout: docs
 permalink: /docs/debug-tool-hit-test-visualization.html
-prevPage: placeholder-fade-duration.html
+prevPage: synchronous-concurrency.html
 nextPage: debug-tool-pixel-scaling.html
 ---
 

_docs/faq.md

@@ -9,22 +9,24 @@ nextPage: containers-overview.html
 ###Common Developer Mistakes
 
 <ul>
-<li><a href = "top-misunderstandings.html#accessing-the-node-s-view-before-it-is-loaded">Do not access a node's view in `-init:`.</a></li>
-<li><a href = "top-misunderstandings.html#thread-safety-in-nodeblocks">Make sure you access your data source outside of a node block.</a></li>
-<li><a href = "top-misunderstandings.html#thread-safety-in-viewBlocks">Take steps to avoid a retain cycle in viewBlocks.</a></li>
+<li><a href = "faq.html#accessing-the-node-s-view-before-it-is-loaded">Do not access a node's view in `-init:`.</a></li>
+<li><a href = "faq.html#make-sure-you-access-your-data-source-outside-the-node-block">Make sure you access your data source outside of a node block.</a></li>
+<li><a href = "faq.html#take-steps-to-avoid-a-retain-cycle-in-viewblocks">Take steps to avoid a retain cycle in viewBlocks.</a></li>
 </ul>
 
 ###Common Conceptual Misunderstandings
 
 <ul>
-<li><a href = "top-misunderstandings.html#cell-node-reusability">ASCellNodes are not reusable.</a></li>
-<li><a href = "top-misunderstandings.html#layoutspecs-are-regenerated">LayoutSpecs are regenerated each time layout is called.</a></li>
+<li><a href = "faq.html#ascellnode-reusability">ASCellNodes are not reusable.</a></li>
+<li><a href = "faq.html#layoutspecs-are-regenerated">LayoutSpecs are regenerated each time layout is called.</a></li>
+<li><a href = "faq.html#layout-api-sizing">The difference between all of the sizes used in our powerful Layout API.</a></li>
+
 </ul>
 
 ###Common Performance Questions
 <ul>
-<li><a href = "top-misunderstandings.html#calayer-s-cornerradius-property-kills-performance">If you care about performance, do not use CALayer's .cornerRadius property (or .shadowPath, border or mask).</a></li>
-<li><a href = "top-misunderstandings.html#asyncdisplaykit-does-not-support-uikit-auto-layout">ASDK does not support UIKit Auto Layout.</a></li>
+<li><a href = "faq.html#calayer-s-cornerradius-property-kills-performance">If you care about performance, do not use CALayer's .cornerRadius property (or .shadowPath, border or mask).</a></li>
+<li><a href = "faq.html#asyncdisplaykit-does-not-support-uikit-auto-layout-or-interfacebuilder">ASDK does not support UIKit Auto Layout.</a></li>
 </ul>
 
 
@@ -63,6 +65,11 @@ AsyncDisplayKit does not use cell reuse, for a number of specific reasons, one s
 A node's layoutSpec gets regenerated every time its `layoutThatFits:` method is called. 
 <br>
 
+### Layout API Sizing
+<br>
+If you're confused by `ASRelativeDimension`, `ASRelativeSize`, `ASRelativeSizeRange` and `ASSizeRange`, check out our <a href = "layout-api-sizing.html">Layout API Sizing guide</a>.
+<br>
+
 ### CALayer's .cornerRadius Property Kills Performance
 <br>
 CALayer's' .cornerRadius property is a disastrously expensive property that should only be used when there is no alternative. It is one of the least efficient, most render-intensive properties on CALayer (alongside shadowPath, masking, borders, etc). These properties trigger offscreen rendering to perform the clipping operation on every frame — 60FPS during scrolling! — even if the content in that area isn't changing. 

_docs/hit-test-slop.md

@@ -2,7 +2,7 @@
 title: Hit Test Slop
 layout: docs
 permalink: /docs/hit-test-slop.html
-prevPage: drawing-priority.html
+prevPage: layoutSpecs.html
 nextPage: batch-fetching-api.html
 ---
 

_docs/layer-backing.md

@@ -2,20 +2,29 @@
 title: Layer Backing
 layout: docs
 permalink: /docs/layer-backing.html
-prevPage: layout-options.html
-nextPage: synchronous-concurrency.html
+prevPage: placeholder-fade-duration.html
+nextPage: subtree-rasterization.html
 ---
 
-In some cases, you can substantially improve your app's performance by using layers instead of views. We recommend enabling layer-backing as a matter of course in any custom node that doesn't need touch handling.
+In some cases, you can substantially improve your app's performance by using layers instead of views. We recommend enabling layer-backing as a matter of course in **any custom node that doesn't need touch handling**.
 
 
 With UIKit, manually converting view-based code to layers is laborious due to the difference in APIs. Worse, if at some point you need to enable touch handling or other view-specific functionality, you have to manually convert everything back (and risk regressions!).
 
 With all AsyncDisplayKit nodes, converting an entire subtree from views to layers is as simple as...
 
-```
+<div class = "highlight-group">
+<span class="language-toggle"><a data-lang="swift" class="swiftButton">Swift</a><a data-lang="objective-c" class = "active objcButton">Objective-C</a></span>
+<div class = "code">
+  <pre lang="objc" class="objcCode">
 rootNode.layerBacked = YES;
-```
+</pre>
+<pre lang="swift" class = "swiftCode hidden">
+rootNode.layerBacked = true
+</pre>
+</div>
+</div>
+<br>
 
 ...and if you need to go back, it's as simple as deleting one line. 
 

_docs/layout-api-sizing.md

@@ -4,12 +4,6 @@ layout: docs
 permalink: /docs/layout-api-sizing.html
 ---
 
-##Question
-
-"I don't think I have a clear understanding of `ASRelativeDimension` / `ASRelativeSizeRange`, and I often see many similar methods to create these structures."
-
-##Answer
-
 The easiest way to understand the compound dimension types in the Layout API is to see all the units in relation to one another.
 
 <img src="/static/images/layout-api-sizing-1.png">

_docs/node-overview.md

@@ -1,5 +1,5 @@
 ---
-title: Node Overview & Hierarchy
+title: Node Subclasses
 layout: docs
 permalink: /docs/node-overview.html
 prevPage: containers-aspagernode.html

_docs/placeholder-fade-duration.md

@@ -3,7 +3,7 @@ title: Placeholder Fade Duration
 layout: docs
 permalink: /docs/placeholder-fade-duration.html
 prevPage: image-modification-block.html
-nextPage: debug-tool-hit-test-visualization.html
+nextPage: layer-backing.html
 ---
 
 <div class = "warning">😑 This page is coming soon...</div>

_docs/subtree-rasterization.md

@@ -2,16 +2,25 @@
 title: Subtree Rasterization
 layout: docs
 permalink: /docs/subtree-rasterization.html
-prevPage: synchronous-concurrency.html
-nextPage: drawing-priority.html
+prevPage: layer-backing.html
+nextPage: synchronous-concurrency.html
 ---
 
 Flattening an entire view hierarchy into a single layer improves performance, but with UIKit, comes with a hit to maintainability and hierarchy-based reasoning. 
 
 With all AsyncDisplayKit nodes, enabling precompositing is as simple as:
 
-```
+<div class = "highlight-group">
+<span class="language-toggle"><a data-lang="swift" class="swiftButton">Swift</a><a data-lang="objective-c" class = "active objcButton">Objective-C</a></span>
+<div class = "code">
+  <pre lang="objc" class="objcCode">
 rootNode.shouldRasterizeDescendants = YES;
-```
+</pre>
+<pre lang="swift" class = "swiftCode hidden">
+rootNode.shouldRasterizeDescendants = true
+</pre>
+</div>
+</div>
+<br>
 
 This line will cause the entire node hierarchy from that point on to be rendered into one layer.

_docs/synchronous-concurrency.md

@@ -2,8 +2,8 @@
 title: Synchronous Concurrency
 layout: docs
 permalink: /docs/synchronous-concurrency.html
-prevPage: layer-backing.html
-nextPage: subtree-rasterization.html
+prevPage: subtree-rasterization.html
+nextPage: debug-tool-hit-test-visualization.html
 ---
 
 Both `ASViewController` and `ASCellNode` have a property called `neverShowPlaceholders`.  
@@ -23,5 +23,6 @@ node.neverShowPlaceholders = true
 </pre>
 </div>
 </div>
+<br>
 
 Usually, if a cell hasn't finished its display pass before it has reached the screen it will show placeholders until it has drawing its content.  Setting this option to YES makes your scrolling node or ASViewController act more like UIKit, and in fact makes AsyncDisplayKit scrolling visually indistinguishable from UIKit's, except that it's faster.

static/main.css

@@ -763,7 +763,7 @@ body {
     margin-top: 1em;
     font-family: BodyFontFamily,"Georgia Pro",Georgia,Times;
     margin: 0;
-    border-top: 3px #008ED4 solid;
+    border-top: 3px #1C9BC7 solid;
     background: #f8f7f5;
     border-radius: 4px;
 }
@@ -781,3 +781,17 @@ pre {
     font-weight: 500;
     color: #333333;
 }
+
+.paddingBetweenCols th {
+    text-align: left;
+    padding: 15px 15px 15px 15px;
+}
+
+.paddingBetweenCols td {
+    padding: 15px 15px 15px 15px;
+/*    border: 1 px solid black;*/
+}
+
+.paddingBetweenCols tr:nth-child(even){
+    background-color: #f2f2f2
+}