diff --git a/site/_includes/docs_contents.html b/site/_includes/docs_contents.html
index 7e7637f3..3360f62c 100644
--- a/site/_includes/docs_contents.html
+++ b/site/_includes/docs_contents.html
@@ -77,6 +77,9 @@
       <li class="{% if page.title == "Resources" %}current{% endif %}">
         <a href="{{ site.url }}/docs/resources">Resources</a>
       </li>
+      <li class="{% if page.title == "Upgrading" %}current{% endif %}">
+        <a href="{{ site.url }}/docs/upgrading">Upgrading</a>
+      </li>
     </ul>
   </aside>
 </div>
diff --git a/site/_posts/2012-07-01-resources.md b/site/_posts/2012-07-01-resources.md
index c14c584c..c319df2d 100644
--- a/site/_posts/2012-07-01-resources.md
+++ b/site/_posts/2012-07-01-resources.md
@@ -2,6 +2,7 @@
 layout: docs
 title: Resources
 prev_section: sites
+next_section: upgrading
 ---
 
 Jekyll’s growing use is producing a wide variety of tutorials, frameworks, extensions, examples, and other resources that can be very helpful. Below is a collection of links to some of the most popular Jekyll resources.
diff --git a/site/_posts/2012-07-01-upgrading.md b/site/_posts/2012-07-01-upgrading.md
new file mode 100644
index 00000000..51a415d6
--- /dev/null
+++ b/site/_posts/2012-07-01-upgrading.md
@@ -0,0 +1,37 @@
+---
+layout: docs
+title: Upgrading
+prev_section: resources
+---
+
+Upgrading from an older version of Jekyll? A few things have changed in 1.0.
+
+### The Jekyll Command
+
+For better clarity, Jekyll now accepts the commands `build` and `serve`. Rather than just `jekyll` and `jekyll --serve`. If you want Jekyll to automatically rebuild each time a file changes, just add the `--watch` flag.
+
+### Custom Config File
+
+Rather than passing individual flags via the command line, you can now pass an entire custom Jekyll config file. This helps to distinguish between environments, or lets you problematically override user-specified defaults. Simply add the `--config` flag, followed by the path to one or more config files.
+
+<div class="note info">
+  <h5 mardown="1">The `--config` flag overrides your `_config.yml` file</h5>
+  <p markdown="1">If you use the `--config` flag, Jekyll will ignore your `_config.yml` file. Want to merge a custom configuration with the normal configuration? No problem. Jekyll will accept more than one custom config file via the command line. Simply pass the URL to both files with the latter file overriding the first.</p>
+</div>
+
+#### As a result, the following command line flags are deprecated:
+
+* `--no-server`
+* `--no-auto`
+* `--auto`
+* `--server`
+* `--url=`
+* `--safe`
+* `--maruku`, `--rdiscount`, and `--redcarpet`
+* `--pygments`
+* `--permalink=`
+* `--paginate`
+
+### Draft posts
+
+### Baseurl
\ No newline at end of file