docs: revert Jade to markdown

closes #1818
Previously, the markdown of some chapters was converted to Jade markup
to support the conditional exclusion of TS prose parts in Dart
chapters. This commit reverts some of that back to clean markdown,
thanks to a few custom directives.

Author: chalin

public/_includes/_scripts-include.jade

@@ -21,6 +21,7 @@ script(src="https://ajax.googleapis.com/ajax/libs/angular_material/1.0.0/angular
 
 <!-- Angular.io Site JS -->
 script(src="/resources/js/site.js")
+script(src="/resources/js/util.js")
 script(src="/resources/js/controllers/app-controller.js")
 script(src="/resources/js/controllers/resources-controller.js")
 script(src="/resources/js/directives/cheatsheet.js")
@@ -32,6 +33,9 @@ script(src="/resources/js/directives/copy.js")
 script(src="/resources/js/directives/code-tabs.js")
 script(src="/resources/js/directives/code-pane.js")
 script(src="/resources/js/directives/code-example.js")
+script(src="/resources/js/directives/if-docs.js")
+script(src="/resources/js/directives/live-example.js")
+script(src="/resources/js/directives/ngio-ex-path.js")
 script(src="/resources/js/directives/scroll-y-offset-element.js")
 
 <!-- GA -->

public/docs/dart/latest/_util-fns.jade

@@ -20,12 +20,14 @@ include ../../../_includes/_util-fns
 - var _indexHtmlDir = 'web';
 - var _mainDir = 'web';
 
+//- Deprecated
 mixin liveExampleLink(linkText, exampleUrlPartName)
   - var text = linkText || 'live example';
   - var ex = exampleUrlPartName || getExampleName();
   - var href = 'http://angular-examples.github.io/' + ex;
   a(href='#{href}' target="_blank")= text
 
+//- Deprecated
 mixin liveExampleLink2(linkText, exampleUrlPartName)
   - var srcText = attributes.srcText || 'view source';
   - var ex = exampleUrlPartName || attributes.example || getExampleName();

public/docs/dart/latest/guide/dependency-injection.jade

@@ -10,21 +10,12 @@ block ctor-syntax
       We also leveraged Dart's constructor syntax for declaring parameters and
       initializing properties simultaneously.
 
-block service-in-its-own-file
-  //- N/A
-
-block one-class-per-file-ts-tradeoffs
-  //- N/A
-
 block injectable-not-always-needed-in-ts
   //- The [Angular 2 Dart Transformer](https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer)
   //- generates static code to replace the use of dart:mirrors. It requires that types be
   //- identified as targets for static code generation. Generally this is achieved
   //- by marking the class as @Injectable (though there are other mechanisms).
 
-block ts-any-decorator-will-do
-  //- N/A
-
 block always-include-paren
   :marked
     Always write `@Injectable()`, not just `@Injectable`.
@@ -43,11 +34,6 @@ block real-logger
       A real implementation would probably use the
       [logging package](https://pub.dartlang.org/packages/logging).
 
-block canonical-provider-expr
-  |  that creates a new instance of the 
-  a(href="../api/core/Provider-class.html") Provider
-  |  class:
-
 block provider-ctor-args
   - var _secondParam = 'named parameter, such as <code>useClass</code>' 
   :marked

public/docs/dart/latest/guide/server-communication.jade

@@ -8,16 +8,9 @@ block includes
   - var _Angular_http_library = 'Dart <a href="' + _httpUrl + '"><b>http</b></a> library'
 
 block demos-list
-  li #[a(href="#http-client") HTTP client: Tour of Heroes]
-  li #[a(href="#cors") JSONP client: Wikipedia to fetch data from a service that does not support CORS] #[b (under development)]
-
-block rxjs-import
-  //- N/A
-
-block http-client
-  
-block system-config-of-http
-  //- N/A
+  :marked
+    - [HTTP client: Tour of Heroes](#http-client)
+    - [JSONP client: Wikipedia to fetch data from a service that does not support CORS (**under development**)](#cors)
 
 block http-providers
   :marked
@@ -50,9 +43,6 @@ block getheroes-and-addhero
     programming in Dart, or the tutorial on 
     [_Asynchronous Programming: Futures_](https://www.dartlang.org/docs/tutorials/futures/).
 
-block rxjs
-  //- N/A
-
 block parse-json
   :marked
     The response data are in JSON string form.
@@ -65,7 +55,7 @@ block error-handling
 block hlc-error-handling
   :marked
     Back in the `HeroListComponent`, we wrapped our call to
-    `#{_priv}heroService.getHeroes()` in a `try` clause. When an exception is
+    `!{_priv}heroService.getHeroes()` in a `try` clause. When an exception is
     caught, the `errorMessage` variable &mdash; which we've bound conditionally in the
     template &mdash; gets assigned to.
 
@@ -75,9 +65,6 @@ block hero-list-comp-add-hero
     awaits for the *service's* asynchronous `addHero()` to return, and when it does,
     the new hero is added to the `heroes` list for presentation to the user.
 
-block promises
-  //- N/A
-
 block wikipedia-jsonp+
   :marked
     Wikipedia offers a modern `CORS` API and a legacy `JSONP` search API.

public/docs/dart/latest/tutorial/index.jade

@@ -1,8 +1,5 @@
 include ../_util-fns
 
 +includeShared('{ts}', 'intro')
-
-p Run the #[+liveExampleLink2('', 'toh-5')].
-
 +includeShared('{ts}', 'main')
 

public/docs/dart/latest/tutorial/toh-pt1.jade

@@ -33,7 +33,8 @@ include ../_util-fns
 
 .callout.is-helpful
   header Source code
-  p Run the #[+liveExampleLink2('', 'toh-1')] for this part.
+  :marked
+    Run the <live-example></live-example> for this part.
 
 :marked
   ## Keep the app compiling and running

public/docs/dart/latest/tutorial/toh-pt2.jade

@@ -6,8 +6,8 @@ include ../_util-fns
   We’ll expand our Tour of Heroes app to display a list of heroes,
   allow the user to select a hero, and display the hero’s details.
 
-p Run the #[+liveExampleLink2('', 'toh-2')] for this part.
-:marked
+  Run the <live-example></live-example> for this part.
+
   Let’s take stock of what we’ll need to display a list of heroes.
   First, we need a list of heroes. We want to display those heroes in the view’s template,
   so we’ll need a way to do that.
@@ -294,8 +294,8 @@ code-example(language="bash").
   * We added the ability to select a hero and show the hero’s details
   * We learned how to use the built-in directives `ngIf` and `ngFor` in a component’s template
 
-p Run the #[+liveExampleLink2('', 'toh-2')] for this part.
-:marked
+  Run the <live-example></live-example> for this part.
+
   ### The Road Ahead
   Our Tour of Heroes has grown, but it’s far from complete.
   We can't put the entire app into a single component.

public/docs/dart/latest/tutorial/toh-pt3.jade

@@ -4,7 +4,7 @@ include ../_util-fns
   Our app is growing.
   Use cases are flowing in for reusing components, passing data to components, and creating more reusable assets. Let's separate the heroes list from the hero details and make the details component reusable.
 
-p Run the #[+liveExampleLink2('', 'toh-3')] for this part.
+  Run the <live-example></live-example> for this part.
 
 .l-main-section
 :marked
@@ -240,7 +240,7 @@ code-example(format=".")
   * We learned to bind a parent component to a child component.
   * We learned to declare the application directives we need in a `directives` list.
 
-p Run the #[+liveExampleLink2('', 'toh-3')] for this part.
+  Run the <live-example></live-example> for this part.
 
 .l-main-section
 :marked

public/docs/dart/latest/tutorial/toh-pt4.jade

@@ -15,7 +15,7 @@ include ../_util-fns
   Because data services are invariably asynchronous,
   we'll finish the chapter with a **!{_Promise}**-based version of the data service.
 
-p Run the #[+liveExampleLink2('', 'toh-4')] for this part.
+  Run the <live-example></live-example> for this part.
 
 .l-main-section
 :marked

public/docs/dart/latest/tutorial/toh-pt5.jade

@@ -18,7 +18,7 @@ figure.image-display
     The [Routing and Navigation](../guide/router.html) chapter covers the router in more detail
     than we will in this tutorial.
 
-p Run the #[+liveExampleLink2('', 'toh-5')] for this part.
+  Run the <live-example></live-example> for this part.
 
 .l-main-section
 :marked
@@ -653,11 +653,10 @@ figure.image-display
 .l-main-section
 :marked
   ## Application structure and code
-p.
-  Review the sample source code in the #[+liveExampleLink2('', 'toh-5')] for this chapter.
+
+  Review the sample source code in the <live-example></live-example> for this chapter.
   Verify that we have the following structure:
 
-:marked
 .filetree
   .file angular2_tour_of_heroes
   .children