diff --git a/modules/angular2/docs/migration/kebab-case.md b/modules/angular2/docs/migration/kebab-case.md
index 82ebf60c82..2298c9b32c 100644
--- a/modules/angular2/docs/migration/kebab-case.md
+++ b/modules/angular2/docs/migration/kebab-case.md
@@ -4,7 +4,9 @@ Angular2 templates are now case-sensitive and use camelCase in many places where
 
 Where you used to write:
 
-    <my-cmp (some-event)="someAction()" [some-property]="expression" #some-var>
+```
+<my-cmp (some-event)="someAction()" [some-property]="expression" #some-var>
+```
 
 in order to:
   - bind to the `someEvent` event,
@@ -13,7 +15,9 @@ in order to:
 
 You should now write:
 
-    <my-cmp (someEvent)="someAction()" [someProperty]="expression" #someVar>
+```
+<my-cmp (someEvent)="someAction()" [someProperty]="expression" #someVar>
+```
 
 Notes:
   - while tag name are case sensitive, the best practice is to use dash case for component elements so that the browser
@@ -28,135 +32,158 @@ Notes:
 
 1. Directives selectors, property bindings, event bindings, template variables and template element attributes should be changed to camel case: 
 
-Examples:
-- `<p *ng-if="cond">` should be changed to `<p *ngIf="cond">`,
-- `<my-cmp [my-prop]="exp">` should be changed to `<my-cmp [myProp]="exp">`,
-- `<my-cmp (my-event)="action()">` should be changed to `<my-cmp (myEvent)="action()">`,
-- `<my-cmp [(my-prop)]="prop">` should be changed to `<my-cmp [(myProp)]="prop">`,
-- `<input #my-input>` should be changed to `<input #myInput>`,
-- `<template ng-for #my-item [ng-for-of]=items #my-index="index">` should be changed to `<template ngFor="#my-item" [ngForOf]=items #myIndex="index">`,
+  Examples:
+  - `<p *ng-if="cond">` should be changed to `<p *ngIf="cond">`,
+  - `<my-cmp [my-prop]="exp">` should be changed to `<my-cmp [myProp]="exp">`,
+  - `<my-cmp (my-event)="action()">` should be changed to `<my-cmp (myEvent)="action()">`,
+  - `<my-cmp [(my-prop)]="prop">` should be changed to `<my-cmp [(myProp)]="prop">`,
+  - `<input #my-input>` should be changed to `<input #myInput>`,
+  - `<template ng-for #my-item [ng-for-of]=items #my-index="index">` should be changed to `<template ngFor="#my-item" [ngForOf]=items #myIndex="index">`,
 
-Note: while the tag names are now case sensitive the best practice is to keep them lower dash cased so that the browser 
-treat them as custom elements. This explains why the `<router-outlet>` component is left unchanged.
+  Note: while the tag names are now case-sensitive the best practice is to keep them lower-dash-cased so that the browser
+  treat them as custom elements. Using dashes in custom element names is required by the [Custom Element HTML Spec](http://www.w3.org/TR/custom-elements/#concepts).
+  This explains why the `<router-outlet>` component is left unchanged.
 
-`on-`, `bindon-`, `bind-` and `var-` prefixes are still part of the canonical syntax and should remain unchanged (lower cased):
-- `on-some-event` should be changed to `on-someEvent`,
-- `bind-my-prop` should be changed to `bind-myProp`,
-- `bindon-my-prop` should be changed to `bindon-myProp`,
-- `var-my-var` should be changed to `var-myVar`.
+  `on-`, `bindon-`, `bind-` and `var-` prefixes are still part of the canonical syntax and should remain unchanged (lower cased):
+  - `on-some-event` should be changed to `on-someEvent`,
+  - `bind-my-prop` should be changed to `bind-myProp`,
+  - `bindon-my-prop` should be changed to `bindon-myProp`,
+  - `var-my-var` should be changed to `var-myVar`.
 
 2. Update variable binding
 
-- `<p #var1="a-b" var-var2="c-d">` should be changed to `<p #var1="aB" var-var2="cD">`  
+  - `<p #var1="a-b" var-var2="c-d">` should be changed to `<p #var1="aB" var-var2="cD">`
 
 3. The `template` attribute values should also be updated in the same way
 
-`<p template="ng-for #my-item of items #my-index = index">` should be changed to `<p template="ngFor #myItem of items #myIndex = index">`.
+  `<p template="ng-for #my-item of items #my-index = index">` should be changed to `<p template="ngFor #myItem of items #myIndex = index">`.
 
-Note that both angular directives and your own directives must be updated in the same way.
+  Note that both angular directives and your own directives must be updated in the same way.
 
 #### Directives and Components
 
 Take the following steps to upgrade your directives and components:
 
 1. Update the selector:
+  ```
+  @Directive({selector: 'tag[attr][name=value]'})
+  @Component({selector: 'tag[attr][name=value]'})
+  ```
 
-    @Directive({selector: 'tag[attr][name=value]'})
-    @Component({selector: 'tag[attr][name=value]'})
+  Tag and attributes names are case sensitive:
+  - For tag names, the best practice is to keep them lower dash cased, do not update them,
+  - For attribute names, the best practice is to convert them from lower dash case to camel case.
 
-Tag and attributes names are case sensitive:
-- For tag names, the best practice is to keep them lower dash cased, do not update them,
-- For attribute names, the best practice is to convert them from lower dash case to camel case.
+  Examples:
+  - `custom-tag` should stay `custom-tag` (do not update tag names),
+  - `[attr-name]` should be updated to `[attrName]`,
+  - `[attr-name=someValue]` should be updated to `[attrName=someValue]`,
+  - `custom-tag[attr-name=someValue]` should be updated to `custom-tag[attrName=someValue]`
 
-Examples:
-- `custom-tag` should stay `custom-tag` (do not update tag names),
-- `[attr-name]` should be updated to `[attrName]`,
-- `[attr-name=someValue]` should be updated to `[attrName=someValue]`,
-- `custom-tag[attr-name=someValue]` should be updated to `custom-tag[attrName=someValue]`
-
-Note: attribute values and classes are still matched case insensitive.
+  Note: attribute values and classes are still matched case insensitive.
 
 2. Update the inputs
+  ```
+  @Directive({inputs: ['myProp', 'myOtherProp: my-attr-name']})
+  ```
 
-    @Directive({inputs: ['myProp', 'myOtherProp: my-attr-name']})
+  As attribute names are now case sensitive, they should be converted from dash to camel case where they are specified.
+  The previous decorator becomes:
 
-As attribute names are now case sensitive, they should be converted from dash to camel case where they are specified.
-The previous decorator becomes:
+  ```
+  @Directive({inputs: ['myProp', 'myOtherProp: myAttrName']})
+  ```
 
-    @Directive({inputs: ['myProp', 'myOtherProp: myAttrName']})
+  Notes:
+    - only the long syntax (with ":") needs not be updated,
+    - `properties` is the legacy name for `inputs` and should be updated in the same way - it is a good idea to replace
+      `properties` with `inputs` at the same time as support for the former will be removed soon.
 
-Notes:
-  - only the long syntax (with ":") needs not be updated,
-  - `properties` is the legacy name for `inputs` and should be updated in the same way - it is a good idea to replace
-    `properties` with `inputs` at the same time as support for the former will be removed soon. 
+  The same applies for the `@Input` decorator:
 
-The same applies for the `@Input` decorator:
+  ```
+  @Input() myProp;
+  @Input('my-attr-name') myProp;
+  ```
 
-    @Input() myProp;
-    @Input('my-attr-name') myProp;
+  That is they only need to be updated when the attribute name is specified:
 
-That is they only need to be updated when the attribute name is specified:  
-
-    @Input() myProp;               // Nothing to update
-    @Input('myAttrName') myProp;   // Convert the attribute name to camel case 
+  ```
+  @Input() myProp;               // Nothing to update
+  @Input('myAttrName') myProp;   // Convert the attribute name to camel case
+  ```
 
 3. Update the outputs
 
-Update the outputs in the same way the inputs are updated:
+  Update the outputs in the same way the inputs are updated:
 
-    @Directive({outputs: ['myEvent', 'myOtherEvent: my-event-name']})
+  ```
+  @Directive({outputs: ['myEvent', 'myOtherEvent: my-event-name']})
+  ```
 
-should be updated to 
+  should be updated to:
 
-    @Directive({outputs: ['myEvent', 'myOtherEvent: myEventName']})
+  ```
+  @Directive({outputs: ['myEvent', 'myOtherEvent: myEventName']})
+  ```
 
-If you use `events` instead of `outputs` you should update in the same way and switch to `outputs` as `events` is deprecated.
+  If you use `events` instead of `outputs` you should update in the same way and switch to `outputs` as `events` is deprecated.
 
-    @Output() myEvent;
-    @Output('my-event-name') myEvent;
+  ```
+  @Output() myEvent;
+  @Output('my-event-name') myEvent;
+  ```
 
-should be changed to   
+  should be changed to:
 
-    @Output() myEvent;
-    @Output('myEventName') myEvent;
+  ```
+  @Output() myEvent;
+  @Output('myEventName') myEvent;
+  ```
 
 4. Update the host bindings
 
-    @Directive({
-      host: {
-        '[some-prop]': 'exp',
-        '[style.background-color]': 'exp',
-        '[class.some-class]': 'exp',
-        '(some-event)': 'action()',
-        'some-attr': 'value'
-      }
-    })
+  ```
+  @Directive({
+    host: {
+      '[some-prop]': 'exp',
+      '[style.background-color]': 'exp',
+      '[class.some-class]': 'exp',
+      '(some-event)': 'action()',
+      'some-attr': 'value'
+    }
+  })
+  ```
 
-should be changed to: 
+  should be changed to:
 
-    @Directive({
-      host: {
-        '[someProp]': 'exp',
-        '[style.background-color]': 'exp',
-        '[class.some-class]': 'exp',
-        '(someEvent)': 'action()',
-        'some-attr': 'value'
-      }
-    })
+  ```
+  @Directive({
+    host: {
+      '[someProp]': 'exp',
+      '[style.background-color]': 'exp',
+      '[class.some-class]': 'exp',
+      '(someEvent)': 'action()',
+      'some-attr': 'value'
+    }
+  })
+  ```
 
-The property bindings (`[...]`) and event bindings (`(...)`) must be updated in the same way as they are updated in a 
-template (reminder: `[attr.]`, `[class.]` and `[style.]` should not be converted to camel case).
+  The property bindings (`[...]`) and event bindings (`(...)`) must be updated in the same way as they are updated in a
+  template (reminder: `[attr.]`, `[class.]` and `[style.]` should not be converted to camel case).
 
 5. Update export name
 
-    @Directive({
-      exportAs: 'some-name'
-    })
-    
-should be changed to     
-
-    @Directive({
-      exportAs: 'someName'
-    })
+  ```
+  @Directive({
+    exportAs: 'some-name'
+  })
+  ```
 
+  should be changed to:
 
+  ```
+  @Directive({
+    exportAs: 'someName'
+  })
+  ```