diff --git a/index.html b/index.html
index a881a02..ca2e333 100644
--- a/index.html
+++ b/index.html
@@ -17,7 +17,7 @@
 </head>
 <body unresolved>
 
-  <core-component-page sources='["core-animated-pages.html","transitions/core-transition-pages"]'></core-component-page>
+  <core-component-page sources='["core-animated-pages.html","transitions/core-transition-pages","transitions/hero-transition.html"]'></core-component-page>
 
 </body>
 </html>
diff --git a/transitions/core-transition-pages.html b/transitions/core-transition-pages.html
index 2280823..398945e 100644
--- a/transitions/core-transition-pages.html
+++ b/transitions/core-transition-pages.html
@@ -37,22 +37,6 @@
 
 See the individual transition documentation for specific details.
 
-Transitions
------------
-
- *    [cross-fade](#cross-fade)
- *    [hero-transition](#hero-transition)
- *    [cascade-transition](#cascade-transition)
-
-<a name="cross-fade"></a>
-### cross-fade 
-
-<a name="hero-transition"></a>
-### hero-transition
-
-<a name="cascade-transition"></a>
-### cascade-transition
-
 @element core-transition-pages
 @status beta
 @homepage github.io
diff --git a/transitions/hero-transition.html b/transitions/hero-transition.html
index bcd652b..825c859 100644
--- a/transitions/hero-transition.html
+++ b/transitions/hero-transition.html
@@ -35,6 +35,59 @@
 </core-style>
 
 
+<!--
+
+`hero-transition` transforms two elements in different pages such that they appear
+to be shared across the pages.
+
+Example:
+
+    <core-animated-pages transition="hero-transition">
+      <section layout horizontal>
+        <div id="div1" flex></div>
+        <div id="div2" flex hero-id="shared" hero></div>
+      </section>
+      <section>
+      <section layout horizontal>
+        <div id="div3" flex hero-id="shared" hero></div>
+        <div id="div4" flex></div>
+      </section>
+      </section>
+    </core-animated-pages>
+
+In the above example, the elements `#div2` and `#div3` shares the same `hero-id`
+attribute and a single element appears to translate and scale smoothly between
+the two positions during a page transition.
+
+Both elements from the source and destination pages must shared the same `hero-id`
+and must both contain the `hero` attribute to trigger the transition. The separate
+`hero` attribute allows you to use binding to configure the transition:
+
+Example:
+
+    <core-animated-pages transition="hero-transition">
+      <section layout horizontal>
+        <div id="div1" flex hero-id="shared" hero?="{{selected == 0}}"></div>
+        <div id="div2" flex hero-id="shared" hero?="{{selected == 1}}"></div>
+      </section>
+      <section>
+      <section layout horizontal>
+        <div id="div3" flex hero-id="shared" hero></div>
+      </section>
+      </section>
+    </core-animated-pages>
+
+In the above example, either `#div1` or `#div2` scales to `#div3` during a page transition,
+depending on the value of `selected`.
+
+Because it is common to share elements with different `border-radius` values, by default
+this transition will also animate the `border-radius` property.
+
+@class hero-transition
+@extends core-transition-pages
+@status beta
+@homepage github.io
+-->
 <polymer-element name="hero-transition" extends="core-transition-pages">
 <script>
 (function() {
