diff --git a/doc-src/content/tutorials/best_practices.haml b/doc-src/content/tutorials/best_practices.haml
deleted file mode 100644
index 0aa111ec..00000000
--- a/doc-src/content/tutorials/best_practices.haml
+++ /dev/null
@@ -1,92 +0,0 @@
----
-title: Best practices
-crumb: Best practices
-layout: tutorial
----
-
-%h3
- Use a Base stylesheet file
-%p
- Create a
- %code
- _base.scss
- %a{ :href => "http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#partials" }
- partial
- to initialize your stylesheets with common variables and (
- %a{ :href => "http://groups.google.com/group/compass-users/browse_frm/thread/0ed216d409476f88" }
- often
- ) the framework utilities you plan to use:
-%h4
- _base.scss
-%pre
- \$blueprint_grid_columns = 24
- \$blueprint_grid_width = 30px
- \$blueprint_grid_margin = 10px
- \$font_color = #333
- \
- @import compass/reset.scss
- @import compass/utilities.scss
- @import blueprint/screen.scss
- \
- \// etc.
-%p
- The
- %code
- _base.scss
- file is also a great place to keep your own custom mixins, so they’re available to any stylesheet that includes it.
-%p
- Then you can include this file in all other stylesheets:
-%h4
- application.scss
-%pre
- @import base.scss
- \
- \#wrapper
- \ +container
- \
- \// etc.
-%p
- It is important to define any compass/framework constants that you want to override in base.scss first, before @import-ing the framework files. See
- %a{ :href => "http://wiki.github.com/chriseppstein/compass/overriding-constants" }
- Overriding Constants
- , for an example of where the number of grid columns for blueprint is overridden/set to 32.
- %br
- Note that you can refer to
- %code
- _base.scss
- without the leading underscore, since it is a
- %a{ :href => "http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#partials" }
- partial
- \.
-%h3
- Write your own Custom Mixins
-%p
- Mixins let you insert any number of style rules into a selector (and its descendants!) with a single line. This is a great way to
- %a{ :href => "http://c2.com/cgi/wiki?DontRepeatYourself" }
- %span.caps
- DRY
- up your stylesheet source code and make it much more maintainable. Using mixins will also make your stylesheet look like self-documented source code — like using descriptive method names in a programming language. It’s much more obvious to read something like
- %code
- +round_corners(6px, #f00)
- than the whole list of rules which define that appearance.
-%h4
- Mixin Example
-
-:markdown
- Mixin for the html element, so the footer stays at the bottom of the screen.
- Relies on the following html structure, and a fixed-height `#footer` element:
-
-
-
-
-
-
-
-
-%p
- A single line is all that’s needed to use the mixin, which moves the implementation details out of the way and replaces them with a clear and concise label:
-%pre
- \html
- \ @include attach_footer( 54px )
diff --git a/doc-src/content/tutorials/best_practices.markdown b/doc-src/content/tutorials/best_practices.markdown
new file mode 100644
index 00000000..e4996d82
--- /dev/null
+++ b/doc-src/content/tutorials/best_practices.markdown
@@ -0,0 +1,107 @@
+---
+title: Best practices
+crumb: Best practices
+layout: tutorial
+---
+### Use a Base stylesheet file
+
+Create a `_base.scss` [partial][1] to initialize your stylesheets with common
+variables and ([often][2]) the framework utilities you plan to use:
+
+#### _base.scss
+
+ $blueprint_grid_columns = 24
+ $blueprint_grid_width = 30px
+ $blueprint_grid_margin = 10px
+ $font_color = #333
+
+ @import compass/reset.scss
+ @import compass/utilities.scss
+ @import blueprint/screen.scss
+
+ // etc.
+
+The `_base.scss` file is also a great place to keep your own custom mixins, so
+they’re available to any stylesheet that includes it.
+
+Then you can include this file in all other stylesheets:
+
+#### application.scss
+
+ @import "base";
+
+ #wrapper {
+ @include container;
+ }
+
+ // etc.
+
+It is important to define any compass/framework constants that you want to override
+in base.scss first, before @import-ing the framework files. See [Overriding
+Constants][3] , for an example of where the number of grid columns for blueprint
+is overridden/set to 32. Note that you can refer to `_base.scss` without the
+leading underscore and without the extension, since it is a [partial][1].
+
+### Write your own Custom Mixins
+
+Mixins let you insert any number of style rules into a selector (and its
+descendants!) with a single line. This is a great way to [DRY][4] up your
+stylesheet source code and make it much more maintainable. Using mixins will
+also make your stylesheet look like self-documented source code -- It’s much
+more obvious to read something like `@include round-corners(6px, #f00)` than the whole
+list of rules which define that appearance.
+
+#### Presentation-free Markup
+
+CSS was created to extract the presentational concerns of a website from the
+webpage content. Following this best practice theoretically results in a website
+that is easier to maintain. However, in reality, the functional limitations of
+CSS force abstractions down into the markup to facilitate the [DRY][4] principle
+of code maintainability. Sass allows us to move our presentation completely to
+the stylesheets because it let's us create abstractions and reuse entirely in
+that context. Read [this blog post][5] for more information on the subject.
+
+Once you have clean markup, style it using Mixins and Inheritance. With clean
+and clear abstractions you should be able to read stylesheets and imagine what
+the webpage will look like without even loading the page in your web browser.
+
+If you find your CSS is getting too bloated due to sharing styles between
+semantic selectors, it may be time to refactor. For instance this stylesheet
+will be unnecessarily bloated:
+
+ @mixin three-column {
+ .container { @include container; }
+ .header,
+ .footer { @include column(24); }
+ .sidebar { @include column(6); }
+ article { @include column(10); }
+ .rightbar { @include column(8); }
+ }
+ body#article,
+ body#snippet,
+ body#blog-post { @include three-column; }
+
+Instead, ask yourself "what non-presentational quality do these pages share in
+common?" In this case, they are all pages of content, so it's better to apply a
+body class of "content" to these pages and then style against that class.
+
+#### Nest selectors, but not too much.
+
+It's easier to style a webpage from scratch or starting from some common base
+point for your application than it is to contend with unwanted styles bleeding
+into your new design. In this way, it is better to use some basic nesting of
+styles using some selector early in the markup tree. And then to refactor as patterns of use emerge to reduce bloat.
+
+It's important to remember that long selectors incur a small rendering
+performance penalty that in aggregate can slow down your web page. There is
+no need to exactly mimic your document structure in your css. Instead nest
+only deep enough that the selector is unique to that part of the document.
+For instance, don't use `table thead tr th` when a simple `th` selector will
+suffice. This might mean that you have to separate your styles into several
+selectors and let the document cascade work to your advantage.
+
+[1]: http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#partials
+[2]: http://groups.google.com/group/compass-users/browse_frm/thread/0ed216d409476f88
+[3]: http://wiki.github.com/chriseppstein/compass/overriding-constants
+[4]: http://c2.com/cgi/wiki?DontRepeatYourself
+[5]: http://chriseppstein.github.com/blog/2009/09/20/why-stylesheet-abstraction-matters/
diff --git a/doc-src/content/tutorials/blueprint.haml b/doc-src/content/tutorials/blueprint.haml
index 2b6b47fe..839c91dd 100644
--- a/doc-src/content/tutorials/blueprint.haml
+++ b/doc-src/content/tutorials/blueprint.haml
@@ -67,9 +67,7 @@ classnames:
%ul
%li
- %a(href="#") Blueprint Buttons
+ %a(href="/docs/reference/blueprint/buttons/") Blueprint Buttons
%li
- %a(href="#") Blueprint Link Icons
+ %a(href="/docs/reference/blueprint/link_icons/") Blueprint Link Icons
-%pre
- TODO: Finish Me!