Basic Layouts

You will use the following layouts throughout your documentation to specify sections and sub-sections of content.

Main Section Title

Main section content...

.l-main-section h2 Section Title p section content...

Sub Section Title

sub section content... This content is related to the main section content and falls within the main section.

.l-sub-section h3 Sub Section Title p sub section content...

Code Examples

Below are some examples of how you can add/customize code examples in a page.

Including a code example from the `_examples` folder

One of the design goals for this documentation was that any code samples that appear within the documentation be 'testable'. In practice this means that a set of standalone testable examples exist somewhere in the same repository as the rest of the documentation. These examples will each typically consist of a collection of html, javascript and css files.

Clearly there also needs to be some mechanism for including fragments of these files into the jade/harp generated html. By convention all of the 'testable' examples within this repository should be created within the docs/_examples folder.

To include an example from somewhere in the doc/_examples folder you can use the makeExample mixin. This mixin along with the makeTabs mixin both require that the 'included' file be marked up with special comment markers. This markup will be described a bit later.

In addition there are several custom gulp tasks that must be run before any of the edits described below will actually appear in the generated documentation. These gulp tasks are documented elsewhere.

In order to use the makeExample or makeTabs mixins each page that references the mixins must include the '_utilFns.jade' file on the current page. This is usually accomplished simply by adding a path to this file at the top of any page that needs either of these mixins.

include ../_util-fns

The syntax for the makeExample mixin is:

+makeExample(filePath, region, title, stylePattern)

filePath: path to the example file under the '_examples' folder
region: (optional or null) region from the example file to display
title: (optional or null) title displayed above the included text.
stylePattern: (optional or null) allows additional styling via regular expression ( described later).

Example:

+makeExample('styleguide/js/src/index.html', null, 'index.html')

This will read the _examples/styleguide/js/src/index.html file and include it with the heading 'index.html'. Note that the file will be properly escaped and color coded according to the extension on the file ( html in this case).

index.html<html>
  <head>
    <title>Documentation Style</title>
    <base href="/">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="styles.css">

    <script src="node_modules/core-js/client/shim.min.js"></script>

    <script src="node_modules/zone.js/dist/zone.js"></script>

    <script src="node_modules/rxjs/bundles/Rx.js"></script>
    <script src="node_modules/@angular/core/bundles/core.umd.js"></script>
    <script src="node_modules/@angular/common/bundles/common.umd.js"></script>
    <script src="node_modules/@angular/compiler/bundles/compiler.umd.js"></script>
    <script src="node_modules/@angular/platform-browser/bundles/platform-browser.umd.js"></script>
    <script src="node_modules/@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js"></script>

    <script src='app.js'></script>
  </head>

  <body>
    <my-app>foo2</my-app>
  </body>

</html>

The second parameter with a value of 'null' will be described later in this document.

There is a similar makeTabs mixin that provides the same service but for multiple examples within a tabbed interface.

+makeTabs(filePaths, regions, titles, stylePatterns)

filePaths: a comma delimited string of filePaths to example files under the '_examples' folder
regions: (optional or null) region from the example file to display
titles: (optional or null) a comma delimited string of titles corresponding to each of the filePaths above.
stylePatterns: (optional or null) allows additional styling via regular expression( described later).

Example:

+makeTabs('styleguide/js/src/index.html, styleguide/js/spec.js', null, 'index.html,unit test')

This will create two tabs, each with its own title and appropriately color coded.

<html> <head> <title>Documentation Style</title> <base href="/"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="styles.css"> <script src="node_modules/core-js/client/shim.min.js"></script> <script src="node_modules/zone.js/dist/zone.js"></script> <script src="node_modules/rxjs/bundles/Rx.js"></script> <script src="node_modules/@angular/core/bundles/core.umd.js"></script> <script src="node_modules/@angular/common/bundles/common.umd.js"></script> <script src="node_modules/@angular/compiler/bundles/compiler.umd.js"></script> <script src="node_modules/@angular/platform-browser/bundles/platform-browser.umd.js"></script> <script src="node_modules/@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js"></script> <script src='app.js'></script> </head> <body> <my-app>foo2</my-app> </body> </html>

describe("Jasmine sample test", function() { it("1+1 should be 2", function() { var result = 1 + 1; expect(result).toBe(2); }); });

Marking up an example file for use by the `makeExample` and `makeTabs` mixins

At a minimum, marking up an example file simply consists of adding a single comment line to the top of the file containing the string #docregion. Following this a second string that is the 'name' of the region is also allowed but not required. A file may have any number of #docregion comments with the only requirement being that the names of each region within a single file be unique. This also means that there can only be one blank docregion.

Example of a simple #docregion

// #docregion describe("Jasmine sample test", function() { it("1+1 should be 2", function() { var result = 1 + 1; expect(result).toBe(2); }); });

If a file only has a single #docregion then the entire file AFTER the #docregion comment is available for inclusion via mixin. Portions of the file can be indicated by surrounding an area of the file with #docregion and an #enddocregion tags. These regions, each with its own name, may be nested to any level and any regions that are not 'ended' explicitly are assumed to be ended automatically at the bottom of the file. Regions may either be ended/closed by name or if the name is left blank then the most recent unclosed docregion defined earlier will be closed. Any individual region within the file is accessible to the makeExample and makeTabs mixins.

Example of a nested #docregion

(function() { // #docregion // #docregion class-w-annotations var AppComponent = ng // #docregion component .Component({ selector: 'my-app', // #enddocregion component // #docregion view template: '

My First Angular App

' }) // #enddocregion view // #docregion class .Class({ constructor: function () { } }); // #enddocregion // #enddocregion

Multiple #docregion tags may be defined on a single line as shown below. In addition, anytime a file contains multiple #docregion tags with the same name they will automatically be combined. Each of the individually tagged sections of the combined document will be separated from one another by a comment consisting of '. . .'. This default separator, known as 'plaster' can be overridden anywhere within the affected file via a #docplaster comment as shown below. This example creates a separator that consists of /* more code here */ in the output file.

// #docplaster more code here // #docregion import,twoparts import { Component } from '@angular/core'; import { bootstrap } from '@angular/platform-browser-dynamic'; // #enddocregion twoparts, import @Component({ selector: 'my-app', template: '

My first Angular App

' }) class AppComponent { } // #docregion bootstrap, twoparts bootstrap(AppComponent); // #enddocregion twoparts doSomethingInteresting(); // #enddocregion

HTML files can also contain #docregion comments:

... <script src="app.js"></script> ...

as can CSS files:

/* #docregion center-global */ .center-global { max-width: 1020px; margin: 0 auto; }

Including a named #docregion via the makeExample or makeTabs mixins.

In order to include just a portion of an example file that has been marked up with a 'named' #docregion you will pass the name of the desired region as the 2nd parameter to the makeExample call.

Example

+makeExample('styleguide/js/src/app.js', 'class-w-annotations', "Extracted region")

is a request to include just the class-w-annotations region from the app.js file in the _examples/styleguide folder and results in the following:

Extracted regionapp.AppComponent =
    ng.core.Component({
      selector: 'my-app',
      template: '<h1 id="output">My First Angular App</h1>'
    })
    .Class({
      constructor: function () { }
    });

Additional styling

In some cases you may want to add additional styling to an external file after it had been included in the documentation. This styling is accomplished via the stylePattern and stylePatterns parameters in the makeExample and makeTabs mixins. A stylePattern is actually just a javascript object where the keys are the names of styles to be applied to some portion of the included text as defined by a regular expression ( or expressions). These regular expressions are the value of each key. Each regular expression MUST specify at least a single capture group; the contents of the capture group being what the style will actually apply to, not the entire regular expression. The idea here is that you may need to include a contextual match in a regular expression but only want your styling to be applied to a subset of the entire regular expression.

Current there are only three types of highlight styles available: Outlined (otl), Pink (pnk), and Black (blk), however the mechanism described above will work with any style defined on the page.

Example

+makeExample('styleguide/js/src/index.html', null, 'index.html', {pnk: /script (src=.*")/g})

Which will mark all of the quoted contents of each script tag within the index.html file in pink.

Note that expression replacement occurs AFTER the fragment has been included and html escaped. This means that your regular expression must use escaped html text; i.e. the '&quot' in the regex above.

src/index.html<html>
  <head>
    <title>Documentation Style</title>
    <base href="/">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="styles.css">

    <script src="node_modules/core-js/client/shim.min.js"></script>

    <script src="node_modules/zone.js/dist/zone.js"></script>

    <script src="node_modules/rxjs/bundles/Rx.js"></script>
    <script src="node_modules/@angular/core/bundles/core.umd.js"></script>
    <script src="node_modules/@angular/common/bundles/common.umd.js"></script>
    <script src="node_modules/@angular/compiler/bundles/compiler.umd.js"></script>
    <script src="node_modules/@angular/platform-browser/bundles/platform-browser.umd.js"></script>
    <script src="node_modules/@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js"></script>

    <script src='app.js'></script>
  </head>

  <body>
    <my-app>foo2</my-app>
  </body>

</html>

A more complicated example might be:

- var stylePattern = { pnk: /script (src=.*")/g, otl: /(\S*my-app.*$)/m }; +makeExample('styleguide/js/src/index.html', null, 'index.html', stylePattern )

Which applies multiple styles and uses an intermediate javascript object as opposed to a literal.

index.html<html>
  <head>
    <title>Documentation Style</title>
    <base href="/">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="styles.css">

    <script src="node_modules/core-js/client/shim.min.js"></script>

    <script src="node_modules/zone.js/dist/zone.js"></script>

    <script src="node_modules/rxjs/bundles/Rx.js"></script>
    <script src="node_modules/@angular/core/bundles/core.umd.js"></script>
    <script src="node_modules/@angular/common/bundles/common.umd.js"></script>
    <script src="node_modules/@angular/compiler/bundles/compiler.umd.js"></script>
    <script src="node_modules/@angular/platform-browser/bundles/platform-browser.umd.js"></script>
    <script src="node_modules/@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js"></script>

    <script src='app.js'></script>
  </head>

  <body>
    <my-app>foo2</my-app>
  </body>

</html>

makeTabs support for stylePatterns is slightly different from the makeExample mixin in that you can also pass in an array of stylePattern objects where each is paired with its corresponding 'tab'. If only a single stylePattern object is passed in then it is assumed to apply to all of the tabs.

-var stylePatterns = [{ pnk: /script (src=.*")/g }, {pnk: /(result)/ }]; +makeTabs('styleguide/js/src/index.html, styleguide/js/spec.js', null, 'index.html,unit test', stylePatterns)

describe("Jasmine sample test", function() { it("1+1 should be 2", function() { var result = 1 + 1; expect(result).toBe(2); }); });

Including a JSON file or just parts of one

To include an '.json' file from somewhere in the doc\_examples folder you can use the makeJson mixin. The makeExample and makeTabs mixins cannot be used for this purpose because there is no standard 'comment' marker in a json file.

The makeJson mixin does however provide a similar capability to selectively pick which portions of the '.json' file to display.

The syntax for the makeJson mixin is:

+makeJson(filePath, jsonConfig, title, stylePattern)

filePath: path to the example file under the '_examples' folder
jsonConfig: (optional) an object that defines which portions of the .json file to select for display.
- rootPath: (optional default=null) a json property path at which the 'paths' parameter below should start.
- paths: a comma delimited list of property paths for those elements to be selected.
- space: (optional default=" " [2 spaces]) a String or Number object that's used to insert white space into the output JSON
title: (optional) title displayed above the included text.
stylePattern: (optional) allows additional styling via regular expression ( described above).

Example:

+makeJson('styleguide/package.1.json', null, "Entire package.json file")

Entire package.json file{
  "name": "angular2-quickstart",
  "version": "1.0.0",
  "scripts": {
    "tsc": "tsc",
    "tsc:w": "tsc -w",
    "lite": "lite-server",
    "start": "concurrently \"npm run tsc:w\" \"npm run lite\" "
  },
  "license": "MIT",
  "dependencies": {
    "angular2": "2.0.0-beta.0",
    "systemjs": "0.19.6",
    "core-js": "^2.4.0",
    "rxjs": "5.0.0-beta.0",
    "zone.js": "0.5.10"
  },
  "devDependencies": {
    "concurrently": "^1.0.0",
    "lite-server": "^1.3.1",
    "typescript": "^1.7.3"
  }
}

A subset of the '.json' file can also be selected.

+makeJson('styleguide/package.1.json', { paths: 'version, scripts.tsc, scripts.start '}, "Selected parts of the package.json file" )

Selected parts of the package.json file{
  "version": "1.0.0",
  "scripts": {
    "tsc": "tsc",
    "start": "concurrently \"npm run tsc:w\" \"npm run lite\" "
  }
}

Styling selected portions of the json is also supported.

+makeJson('styleguide/package.1.json', {paths: 'dependencies'}, "package.json dependencies", { pnk: [/(\S*zone.*)/, /(\Score-js.*)/, /(\Ssystem.*)/ ]})

package.json dependencies{
  "dependencies": {
    "angular2": "2.0.0-beta.0",
    "systemjs": "0.19.6",
    "core-js": "^2.4.0",
    "rxjs": "5.0.0-beta.0",
    "zone.js": "0.5.10"
  }
}

Inline code and code examples provided directly i.e. not from an example file.

The makeExample and makeTabs mixins are both both built on top of a custom jade 'style'; code-example. In those cases where you want to include code directly inline i.e. not from some external file; you can use this style. This style has several named attributes

code-example attributes

name: Name displayed in Tab (required for tabs)
language: javascript, html, etc.
escape: html (escapes html, woot!)
format: linenums (or linenums:4 specify starting line)

Example

code-example(format="linenums" language="javascript"). //SOME CODE

Specify starting line number

code-example(language="html" format="linenums:4"). var title = "This starts on line four";

Specify a language

Prettify makes a best effort to guess the language but works best with C-like and HTML-like languages. For others, there are special language handlers that are chosen based on language hints. Add a class that matches your desired language (example below uses .lang-html)

<h1>Title</h1> <p>This is some copy...</p>

Code Highlighting

There are three types of highlights available Outlined, Pink, and Black. You can see examples below and the class names needed for each type.

// Pink Background Version // class="pnk" var elephants = "The pink elephants were marching..."; // Black Background Version // class="blk" var night = "The night was pitch black."; // Outlined Version // class="otl" var match = "The bird ate bird seed near the bird bath ";

Code Tabs

Code Tabs are a great way to show different languages and versions of a particular piece of code. When using these tabs make sure the content is always related.

// ES5 var hello = 'blah';

// TypeScript var hello = 'blah';

To create code tabs simply use the directives below

code-tabs code-pane(format="linenums" name="Tab 1"). // TAB 1 CONTENT code-pane(format="linenums" name="Tab 2"). // TAB 2 CONTENT

Combining makeExample, makeTabs mixins with code-example style attributes

As mentioned above the makeExample and makeTabs mixins are built on top of the code-example style. By default the mixins automatically determine a language based on the example file's extensions and always include line numbers.

You can override this behavior by including code-example attributes within parentheses after the mixin parameters.

Example

+makeExample('styleguide/js/src/app.js', "class-w-annotations")(format="linenums:15")

Starts the numbering of the example at line 15.

app.AppComponent =
    ng.core.Component({
      selector: 'my-app',
      template: '<h1 id="output">My First Angular App</h1>'
    })
    .Class({
      constructor: function () { }
    });

Or to suppress line numbering completely you can use

+makeExample('styleguide/js/src/app.js', 'class-w-annotations')(format=".")

app.AppComponent =
    ng.core.Component({
      selector: 'my-app',
      template: '<h1 id="output">My First Angular App</h1>'
    })
    .Class({
      constructor: function () { }
    });

Code examples in angular/angular source code

References to embedded example code in the angular/angular source make use of the same mixins as defined above, but with a slightly different syntax. Inline tags in source code comments like {@example ...} and {@exampleTabs ...} actually generate 'makeExample' and 'makeTabs' mixins calls in the documentation. The order of 'arguments' in the inline tags is also the same as that of the mixins defined above. However, optional parameters can also be specified via name (optionally prefixed with a '-'), as will be shown by example below. Parameters that include spaces should be enclosed in either single or double quotes. This syntax is intended to mirror standard command line argument patterns.

The '@example' and '@exampleTabs' inline tags MUST always appear at the beginning of a line. Example files referenced by inline tags are all assumed to be in the 'modules/@angular' folder in the angular/angular repo.

@example inline tag parameters

filePath: path to the example file under the '_examples' folder
region: (optional or null) region from the example file to display
title: (optional or null) title displayed above the included text.
stylePattern: (optional or null) allows additional styling via regular expression ( described later).

Examples

/** * An example with no region * {@example core/directives/ng_if_spec.ts -title='Whole other component' } * * An example with a region and a title both specified by name * {@example core/directives/ng_if_spec.ts region='ng-if' title='Partial' } * * Another example with a region and a title with only the title specified explicitly. * {@example core/directives/ng_if_spec.ts foo title='Foo' } **/

@exampleTabs inline tag parameters

filePaths: a comma delimited string of filePaths to example files under the '_examples' folder
regions: (optional or null) region from the example file to display
titles: (optional or null) a comma delimited string of titles corresponding to each of the filePaths above.
stylePatterns: (optional or null) allows additional styling via regular expression( described later).

Examples

/** * An example with multiple tabs each with its own region and title. * {@exampleTabs core/directives/test1_spec.ts,core/directives/test2_spec.ts regions='aaa,bbb,' -titles='Test 1,Test 2' } * **/

Cross references to Developer guide pages in angular/angular source comments.

The '{@linkDevGuide ... }' inline tag is intended to be used to create links from api documentation to dev guide documentation.

@linkDevGuide inline tag parameters

filePath: a filePath that points to a jade page in the DevGuide without the .jade extension ( under public/docs ).
title: The title of link. If the title is omitted an attempt will be made to determine the title of the jade page being pointed to. If not found the then title will simply be the link.
Examples

/** * An link to the Developer guide example with a link title * This can appear anywhere in a comment line: {@linkDevGuide /js/latest/guide/gettingStarted 'Getting Started' } * and the same link can also be expressed with an explicit 'title' param * {@linkDevGuide /js/latest/guide/gettingStarted title='Getting Started' } * Or... an attempt will be made to infer the title if it is omitted. * {@linkDevGuide /js/latest/guide/gettingStarted } **/

Alerts

警告

Please use alerts sparingly throughout the docs. They are meant to draw attention on important occasions. Alerts should not be used for multi-line content (user callouts insteads) or stacked on top of each other.

请在文档中严谨的使用警告。这意味着只在重要的场合用它吸引注意力。不要用警告表现多行内容(使用插图代替)，也不要把它们堆叠在一起。

Adding an alert

添加警告

A very critical alert

非常关键的警告

A very important alert

非常重要的警告

A very helpful alert

非常有用的警告

.alert.is-critical 非常关键的警告
.alert.is-important 非常重要的警告
.alert.is-helpful 非常有用的警告

Callouts

Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention on important occasions. Unlike alerts, callouts are designed to display multi-line content.

Adding a Callout

A Critical Title

Pitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix

A Very Important Title

A vePitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix

A Very Helpful Title

.callout.is-critical
  header A Critical Title
  p Pitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix

.callout.is-important
  header A Very Important Title
  p A vePitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix

.callout.is-helpful
  header A Very Helpful Title
  p Pitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles tousled Truffaut yr. Semiotics viral freegan VHS, Shoreditch disrupt McSweeney's. Intelligentsia kale chips Vice four dollar toast, Schlitz crucifix

Tables

Tables can be used to present tabular data as it relates to each other.

Adding an table

Framework	Task	Speed
AngularJS v.1.3	Routing	fast
AngularJS v.1.4	Routing	faster
Angular	Routing	fastest :)

table
  tr
    th Framework
    th Task
    th Speed
  tr
    td AngularJS v.1.3
    td Routing
    td fast

Asides

You this for content that is related in a tangential way but not critical to learning, it can be ignored. The paragraph that includes this element should always surround it with text.

Adding an aside

Etsy artisan Thundercats, authentic sustainable bitters wolf roof party meditation 90's asymmetrical XOXO hoodie. Twee umami cray iPhone. Chillwave shabby chic tilde occupy sriracha squid Brooklyn street art. Selvage heirloom kogi American Apparel bicycle rights. Carles Etsy Truffaut mlkshk trust fund. Jean shorts fashion axe Williamsburg wolf cardigan beard, twee blog locavore organic. Cred skateboard dreamcatcher, taxidermy Bushwick actually aesthetic normcore fanny pack.

aside.is-right Did you know that hipsum is a replacement for Lorem Ipsum? To find out more visit hipsum.co

p.
  Etsy artisan Thundercats, authentic sustainable bitters
  wolf roof party meditation 90's asymmetrical XOXO hoodie.
  Twee umami cray iPhone. Chillwave shabby chic tilde
  occupy sriracha squid Brooklyn street art.

Images

To maintain visual consistency across documentation chapters, please follow the best practices for authors outlined in the Image Guide.

The browser background template used for outlining screenshots is here.

Main Section Title

Sub Section Title

Including a code example from the _examples folder

+makeExample(filePath, region, title, stylePattern)

Example:

+makeTabs(filePaths, regions, titles, stylePatterns)

Example:

Marking up an example file for use by the makeExample and makeTabs mixins

Example of a simple #docregion

Example of a nested #docregion

My First Angular App

My first Angular App

Including a named #docregion via the makeExample or makeTabs mixins.

Example

Additional styling

Example

Including a JSON file or just parts of one

+makeJson(filePath, jsonConfig, title, stylePattern)

Example:

Inline code and code examples provided directly i.e. not from an example file.

code-example attributes

Example

Specify starting line number

Specify a language

Code Highlighting

Code Tabs

Combining makeExample, makeTabs mixins with code-example style attributes

Example

Code examples in angular/angular source code

@example inline tag parameters

Examples

@exampleTabs inline tag parameters

Examples

Cross references to Developer guide pages in angular/angular source comments.

@linkDevGuide inline tag parameters

Examples

Adding an alert

添加警告

Adding a Callout

Adding an table

Adding an aside

Including a code example from the `_examples` folder

Marking up an example file for use by the `makeExample` and `makeTabs` mixins