docs(security): hide TOC for Dart; other minor copyedits (#3017)

public/docs/_examples/security/ts/app/bypass-security.component.html

@@ -1,20 +1,17 @@
 <!--#docregion -->
 <h3>Bypass Security Component</h3>
 
-<!--#docregion dangerous-url -->
+<!--#docregion URL -->
 <h4>An untrusted URL:</h4>
 <p><a class="e2e-dangerous-url" [href]="dangerousUrl">Click me</a></p>
 <h4>A trusted URL:</h4>
 <p><a class="e2e-trusted-url" [href]="trustedUrl">Click me</a></p>
-<!--#enddocregion dangerous-url -->
+<!--#enddocregion URL -->
 
-<!--#docregion iframe-videoid -->
+<!--#docregion iframe -->
 <h4>Resource URL:</h4>
 <p><label>Showing: <input (input)="updateVideoUrl($event.target.value)"></label></p>
 <p>Trusted:</p>
 <iframe class="e2e-iframe-trusted-src" width="640" height="390" [src]="videoUrl"></iframe>
 <p>Untrusted:</p>
 <iframe class="e2e-iframe-untrusted-src" width="640" height="390" [src]="dangerousVideoUrl"></iframe>
-<!--#enddocregion iframe-videoid -->
-
-<!--#enddocregion -->

public/docs/_examples/security/ts/app/inner-html-binding.component.ts

@@ -6,7 +6,7 @@ import { Component } from '@angular/core';
   selector: 'inner-html-binding',
   templateUrl: 'inner-html-binding.component.html',
 })
-// #docregion inner-html-controller
+// #docregion class
 export class InnerHtmlBindingComponent {
   // For example, a user/attacker-controlled value from a URL.
   htmlSnippet = 'Template <script>alert("0wned")</script> <b>Syntax</b>';

public/docs/ts/latest/guide/security.jade

@@ -8,8 +8,9 @@ block includes
 
   For more information about the attacks and mitigations described below, see [OWASP Guide Project](https://www.owasp.org/index.php/Category:OWASP_Guide_Project).
 
-.l-main-section
++ifDocsFor('ts')
-:marked
+  .l-main-section
+  :marked
     # Contents:
 
     * [Reporting vulnerabilities](#report-issues).
@@ -19,6 +20,7 @@ block includes
     * [HTTP-Level vulnerabilities](#http).
     * [Auditing Angular applications](#code-review).
 
+:marked
   Try the <live-example></live-example> of the code shown in this page.
 
 .l-main-section
@@ -103,15 +105,17 @@ h2#xss Preventing cross-site scripting (XSS)
   a value that an attacker might control into `innerHTML` normally causes an XSS
   vulnerability. For example, code contained in a `<script>` tag is executed:
 
-+makeExcerpt('app/inner-html-binding.component.ts ()', 'inner-html-controller')
++makeExcerpt('app/inner-html-binding.component.ts', 'class')
 
-:marked
+block html-sanitization
+  :marked
     Angular recognizes the value as unsafe and automatically sanitizes it, which removes the `<script>`
     tag but keeps safe content such as the text content of the `<script>` tag, or the `<b>` element.
 
-figure.image-display
+  figure.image-display
       img(src='/resources/images/devguide/security/binding-inner-html.png'
           alt='A screenshot showing interpolated and bound HTML values')
+
 :marked
   ### Avoid direct use of the DOM APIs
 
@@ -144,9 +148,10 @@ figure.image-display
   the server. Do not generate Angular templates on the server side using a templating language; doing this
   carries a high risk of introducing template-injection vulnerabilities.
 
-.l-main-section
+block bypass-security-apis
-h2#bypass-security-apis Trusting safe values
+  .l-main-section
-:marked
+  h2#bypass-security-apis Trusting safe values
+  :marked
     Sometimes applications genuinely need to include executable code, display an `<iframe>` from some
     URL, or construct potentially dangerous URLs. To prevent automatic sanitization in any of these 
     situations, you can tell Angular that you inspected a value, checked how it was generated, and made 
@@ -167,20 +172,20 @@ h2#bypass-security-apis Trusting safe values
     your intended use of the value. Imagine that the following template needs to bind a URL to a
     `javascript:alert(...)` call:
 
-+makeExcerpt('app/bypass-security.component.html ()', 'dangerous-url')
+  +makeExcerpt('app/bypass-security.component.html', 'URL')
 
-:marked
+  :marked
     Normally, Angular automatically sanitizes the URL, disables the dangerous code, and
     in development mode, logs this action to the console. To prevent
     this, you can mark the URL value as a trusted URL using the `bypassSecurityTrustUrl` call:
 
-+makeExcerpt('app/bypass-security.component.ts ()', 'trust-url')
+  +makeExcerpt('app/bypass-security.component.ts ()', 'trust-url')
 
-figure.image-display
+  figure.image-display
       img(src='/resources/images/devguide/security/bypass-security-component.png'
           alt='A screenshot showing an alert box created from a trusted URL')
 
-:marked
+  :marked
     If you need to convert user input into a trusted value, use a
     controller method. The template below allows users to enter a YouTube video ID and load the
     corresponding video in an `<iframe>`. The `<iframe src>` attribute is a resource URL security
@@ -188,18 +193,19 @@ figure.image-display
     could execute. So call a method on the controller to construct a trusted video URL, that causes
     Angular to then allow binding into `<iframe src>`:
 
-+makeExcerpt('app/bypass-security.component.html ()', 'iframe-videoid')
+  +makeExcerpt('app/bypass-security.component.html', 'iframe')
-+makeExcerpt('app/bypass-security.component.ts ()', 'trust-video-url')
+  +makeExcerpt('app/bypass-security.component.ts ()', 'trust-video-url')
 
-.l-main-section
+block http
-h2#http HTTP-level vulnerabilities
+  .l-main-section
-:marked
+  h2#http HTTP-level vulnerabilities
+  :marked
     Angular has built-in support to help prevent two common HTTP vulnerabilities, cross-site request
     forgery (CSRF or XSRF) and cross-site script inclusion (XSSI). Both of these must be mitigated primarily 
     on the server side, but Angular ships helpers to make integration on the client side easier.
 
-h3#xsrf Cross-site request forgery
+  h3#xsrf Cross-site request forgery
-:marked
+  :marked
     In a cross-site request forgery (CSRF or XSRF), an attacker tricks the user into visiting
     a different web page (e.g. `evil.com`) with malignant code that secretly sends a malicious request 
     to your application's web server (e.g. `example-bank.com`). 
@@ -241,15 +247,15 @@ h3#xsrf Cross-site request forgery
 
     Your server may use a different cookie or header name for this purpose.
     An Angular application can customize cookie and header names by providing its own `CookieXSRFStrategy` values.
-code-example(language="typescript").
+  code-example(language="typescript").
     { provide: XSRFStrategy, useValue: new CookieXSRFStrategy('myCookieName', 'My-Header-Name') }
-:marked
+  :marked
     Or you can implement and provide an entirely custom `XSRFStrategy`:
 
-code-example(language="typescript").
+  code-example(language="typescript").
     { provide: XSRFStrategy, useClass: MyXSRFStrategy }
 
-:marked
+  :marked
     For information about CSRF at the Open Web Application Security Project (OWASP), see
     <a href="https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29" target="_blank">Cross-Site Request Forgery (CSRF)</a> and
     <a href="https://www.owasp.org/index.php/CSRF_Prevention_Cheat_Sheet" target="_blank">Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet</a>.
@@ -259,8 +265,8 @@ code-example(language="typescript").
     See also Dave Smith's easy-to-understand 
     <a href="https://www.youtube.com/watch?v=9inczw6qtpY" target="_blank" title="Cross Site Request Funkery Securing Your Angular Apps From Evil Doers">talk on XSRF at AngularConnect 2016</a>.
 
-h3#xssi Cross-site script inclusion (XSSI)
+  h3#xssi Cross-site script inclusion (XSSI)
-:marked
+  :marked
     Cross-site script inclusion, also known as JSON vulnerability, can allow an attacker's website to
     read data from a JSON API. The attack works on older browsers by overriding native JavaScript
     object constructors, and then including an API URL using a `<script>` tag.