Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

docs: revert Jade to markdown #1818

Closed
wants to merge 1 commit into from

Conversation

chalin
Copy link
Contributor

@chalin chalin commented Jul 4, 2016

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. (It also fixes a few errors due to markdown syntax being left in Jade markup.)

For example:

-p.
-  We can confirm in the #[+liveExampleLink()] that the #[i flying heroes]
-  display updates as we enter new heroes even when we mutate the
-  #[code heroes] #{_array}.
-  ... a final version of #[code #[+adjExPath('app/main.ts')]]
+:marked
+  We can confirm in the <live-example></live-example> that the _flying heroes_
+  display updates as we enter new heroes even when we mutate the `heroes` #{_array}.
+  ... a final version of <span ngio-ex>app/main.ts></span>

So no more #[...] Jade interpolation in such cases. Notice the live-example directive which replaces the use of the Jade mixin with a similar name. The ngio-ex directive is used to qualify example path names.

Jade lists with conditional text can be difficult to read; now markdown is fine:

-ul
-  li #[a(href="#http-client") HTTP client sample overview]
-  li #[a(href="#fetch-data") Fetch data with http.get]
-  +ifDocsFor('ts')
-    li #[a(href="#rxjs") RxJS Observable of HTTP Responses]
-    li #[a(href="#enable-rxjs-operators") Enabling RxJS Operators]
-  ...
+:marked
+  - [HTTP client sample overview](#http-client)
+  - [Fetch data with http.get](#fetch-data)
+  <li if-docs="ts"> [RxJS Observable of HTTP Responses](#rxjs)</li>
+  <li if-docs="ts"> [Enabling RxJS Operators](#enable-rxjs-operators)</li>
+  ...

And it's much easier to do intra-paragraph conditionals now (no more &nbsp;):

-h1 Try it!
-p
-  | Try the #[+liveExampleLink2()] which loads the sample app
-  +ifDocsFor('ts')
-    | &nbsp;in #[a(href="http://plnkr.co/" title="Plunker" target="_blank") plunker]
-  | &nbsp;and displays the simple message:
+:marked
+  # Try it!
+
+  Try the <live-example></live-example> which loads the sample app
+  <span if-docs="ts">
+    in <a href="http://plnkr.co/" title="Plunker" target="_blank">plunker</a>
+  </span>
+  and displays the simple message:

@chalin
Copy link
Contributor Author

chalin commented Jul 4, 2016

@Foxandxss @wardbell @kwalrath : ready for review. I think you'll agree that the markdown is easier on the eyes :).

@Foxandxss
Copy link
Member

Sounds good for me.

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.
@chalin chalin force-pushed the chalin-revert-to-markdown-0703 branch from d1907db to fa92add Compare July 4, 2016 21:17
@wardbell
Copy link
Contributor

wardbell commented Jul 6, 2016

I like what I see here. I didn't review every detail; deferring to @Foxandxss on those.

@wardbell wardbell closed this in b0e0d94 Jul 6, 2016
@chalin chalin deleted the chalin-revert-to-markdown-0703 branch July 6, 2016 11:24
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants