` that has the `l-sub-section` CSS class. You should write the subsection content in markdown. Here is an example of a subsection `

` surrounding the subsection content written in markdown.

You'll learn about styles for live examples in the [section below](guide/docs-style-guide#live-examples "Live examples").

```html

You'll learn about styles for live examples in the [section below](guide/docs-style-guide#live-examples "Live examples").

``` Note that at least one blank line must follow the opening `

`. A blank line before the closing `

` is customary but not required. ## Table of contents Most pages display a table of contents (TOC). The TOC appears in the right panel when the viewport is wide. When narrow, the TOC appears in an expandable/collapsible region near the top of the page. You should not create your own TOC by hand. The TOC is generated automatically from the page's main and secondary section headers. To exclude a heading from the TOC, create the heading as an `

` or `

` element with a class called 'no-toc'. You can't do this with markdown. ```html

This heading is not displayed in the TOC

``` You can turn off TOC generation for the _entire_ page by writing the title with an `

` tag and the `no-toc` class. ```html

A guide without a TOC

``` ## Navigation The navigation links at the top, left, and bottom of the screen are generated from the JSON configuration file, `content/navigation.json`. The authority to change the `navigation.json` file is limited to a few core team members. But for a new guide page, you should suggest a navigation title and position in the left-side navigation panel called the "side nav". Look for the `SideNav` node in `navigation.json`. The `SideNav` node is an array of navigation nodes. Each node is either an _item_ node for a single document or a _header_ node with child nodes. Find the header for your page. For example, a guide page that describes an Angular feature is probably a child of the `Fundamentals` header. ```html { "title": "Fundamentals", "tooltip": "The fundamentals of Angular", "children": [ ... ] } ``` A _header_ node child can be an _item_ node or another _header_ node. If your guide page belongs under a sub-header, find that sub-header in the JSON. Add an _item_ node for your guide page as a child of the appropriate _header_ node. It probably looks something like this one. ```html { "url": "guide/architecture", "title": "Architecture", "tooltip": "The basic building blocks of Angular applications." } ``` A navigation node has the following properties: * `url`- the URL of the guide page (_item node only_). * `title`- the text displayed in the side nav. * `tooltip` - text that appears when the reader hovers over the navigation link. * `children` - an array of child nodes (_header node only_). * `hidden` - defined and set true if this is a guide page that should _not_ be displayed in the navigation panel. Rarely needed, it is a way to hide the page from navigation while making it available to readers who should know about it. _This_ "Authors Style Guide" is a hidden page.

Do not create a node that is both a _header_ and an _item_ node. That is, do not specify the `url` property of a _header_ node.

The current guidelines allow for a three-level navigation structure with two header levels. Don't add a third header level.

## Code snippets Guides are rich in examples of working Angular code. Example code can be commands entered in a terminal window, a fragment of TypeScript or HTML, or an entire code file. Whatever the source, the doc viewer renders them as "code snippets", either individually with the [_code-example_](#code-example "code-example") component or as a tabbed collection with the [_code-tabs_](#code-tabs "code-tabs") component. {@a code-example} ### Code example You can display a simple, inline code snippet with the markdown backtick syntax. We generally prefer to display a code snippet with the Angular documentation _code-example_ component represented by the `` tag.

Inline code-snippets

You should source code snippets [from working sample code](#from-code-samples) when possible. But there are times when an inline snippet is the better choice. For terminal input and output, put the content between `` tags, set the CSS class to `code-shell`, and set the language attribute to `sh` as in this example. npm start ```html npm start ``` Inline, hand-coded snippets like this one are _not_ testable and, therefore, are intrinsically unreliable. This example belongs to the small set of pre-approved, inline snippets that includes user input in a command shell or the _output_ of some process. **Do not write inline code snippets** unless you have a good reason and the editor's permission to do so. In all other cases, code snippets should be generated automatically from tested code samples. {@a from-code-samples}

Code snippets and code samples

One of the documentation design goals is that guide page code snippets should be examples of real, working code. We meet this goal by displaying code snippets that are derived directly from standalone code samples, written specifically for these guide pages. The author of a guide page is responsible for the code sample that supports that page. The author must also write end-to-end tests for the sample. Code samples are located in sub-folders of the `content/examples` directory of the `angular/angular` repository. An example folder name should be the same as the guide page it supports.

A guide page might not have its own sample code. It might refer instead to a sample belonging to another page.

The Angular CI process runs all end-to-end tests for every Angular PR. Angular re-tests the samples after every new version of a sample and every new version of Angular itself. When possible, every snippet of code on a guide page should be derived from a code sample file. You tell the Angular documentation engine which code file - or fragment of a code file - to display by configuring `` attributes. #### Code snippet from a file _This_ "Authors Doc Style Guide" has its own sample application, located in the `content/examples/docs-style-guide` folder. The following _code-example_ displays the sample's `app.module.ts`. Here's the brief markup that produced that lengthy snippet: ```html ``` You identified the snippet's source file by setting the `path` attribute to sample folder's location _within_ `content/examples`. In this example, that path is `docs-style-guide/src/app/app.module.ts`. You added a header to tell the reader where to find the file by setting the `title` attribute. Following convention, you set the `title` attribute to the file's location within the sample's root folder.

Unless otherwise noted, all code snippets in this page are derived from sample source code located in the `content/examples/docs-style-guide` directory.

The doc tooling reports an error if the file identified in the path does not exist **or is _git_-ignored**. Most `.js` files are _git_-ignored. If you want to include an ignored code file in your project and display it in a guide you must _un-ignore_ it. The preferred way to un-ignore a file is to update the `content/examples/.gitignore` like this: # my-guide !my-guide/src/something.js !my-guide/more-javascript*.js

#### Code-example attributes You control the _code-example_ output by setting one or more of its attributes: * `path`- the path to the file in the `content/examples` folder. * `title`- the header of the code listing. * `region`- displays the source file fragment with that region name; regions are identified by _docregion_ markup in the source file, as explained [below](#region "Displaying a code fragment"). * `linenums`- value may be `true`, `false`, or a `number`. When not specified, line numbers are automatically displayed when there are greater than 10 lines of code. The rarely used `number` option starts line numbering at the given value. `linenums=4` sets the starting line number to 4. * `class`- code snippets can be styled with the CSS classes `no-box`, `code-shell`, and `avoid`. * `hideCopy`- hides the copy button * `language`- the source code language such as `javascript`, `html`, `css`, `typescript`, `json`, or `sh`. This attribute only works for inline examples. {@a region} #### Displaying a code fragment Often you want to focus on a fragment of code within a sample code file. In this example, you focus on the `AppModule` class and its `NgModule` metadata. First you surround that fragment in the source file with a named _docregion_ as described [below](#source-code-markup). Then you reference that _docregion_ in the `region` attribute of the `` like this ```html ``` A couple of observations: 1. The `region` value, `"class"`, is the name of the `#docregion` in the source file. Confirm that by looking at `content/examples/docs-style-guide/src/app/app.module.ts` 1. Omitting the `title` is fine when the source of the fragment is obvious. We just said that this is a fragment of the `app.module.ts` file which was displayed immediately above, in full, with a header. There's no need to repeat the header. 1. The line numbers disappeared. By default, the doc viewer omits line numbers when there are fewer than 10 lines of code; it adds line numbers after that. You can turn line numbers on or off explicitly by setting the `linenums` attribute. #### Example of bad code Sometimes you want to display an example of bad code or bad design. You should be careful. Readers don't always read carefully and are likely to copy and paste your example of bad code in their own applications. So don't display bad code often. When you do, set the `class` to `avoid`. The code snippet will be framed in bright red to grab the reader's attention. Here's the markup for an "avoid" example in the [_Angular Style Guide_](guide/styleguide#style-05-03 "Style 05-03: components as elements"). ```html ``` {@a code-tabs} ### Code Tabs Code tabs display code much like _code examples_ do. The added advantage is that they can display multiple code samples within a tabbed interface. Each tab is displayed using _code pane_. #### Code-tabs attributes * `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are enabled only when code for a tab pane has greater than 10 lines of code. #### Code-pane attributes * `path` - a file in the content/examples folder * `title` - seen in the header of a tab * `linenums` - overrides the `linenums` property at the `code-tabs` level for this particular pane. The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are enabled only when the number of lines of code are greater than 10. The next example displays multiple code tabs, each with its own title. It demonstrates control over display of line numbers at both the `` and `` levels.

Here's the markup for that example. Note how the `linenums` attribute in the `` explicitly disables numbering for all panes. The `linenums` attribute in the second pane restores line numbering for _itself only_. ```html

``` {@a source-code-markup} ## Source code markup You must add special code snippet markup to sample source code files before they can be displayed by `` and `` components.

The sample source code for this page, located in `context/examples/docs-style-guide`, contains examples of every code snippet markup described in this section.

Code snippet markup is always in the form of a comment. Here's the default _docregion_ markup for a TypeScript or JavaScript file: ``` // #docregion ... some code ... // #enddocregion ``` Different file types have different comment syntax so adjust accordingly. ```html ... some HTML ... ``` ``` /* #docregion */ ... some CSS ... /* #enddocregion */ ``` The doc generation process erases these comments before displaying them in the doc viewer. It also strips them from stackblitz and sample code downloads.

Code snippet markup is not supported in JSON files because comments are forbidden in JSON files. See [below](#json-files) for details and workarounds.

#### _#docregion_ The _#docregion_ is the most important kind of code snippet markup. The `` and `` components won't display a source code file unless it has a _#docregion_. The _#docregion_ comment begins a code snippet region. Every line of code _after_ that comment belongs in the region _until_ the code fragment processor encounters the end of the file or a closing _#enddocregion_.

The `src/main.ts` is a simple example of a file with a single _#docregion_ at the top of the file.

#### Named _#docregions_ You'll often display multiple snippets from different fragments within the same file. You distinguish among them by giving each fragment its own _#docregion name_ as follows. ``` // #docregion region-name ... some code ... // #enddocregion region-name ``` Remember to refer to this region by name in the `region` attribute of the `` or `` as you did in an example above like this: ```html ``` The _#docregion_ with no name is the _default region_. Do _not_ set the `region` attribute when referring to the default _#docregion_. #### Nested _#docregions_ You can nest _#docregions_ within _#docregions_ ``` // #docregion ... some code ... // #docregion inner-region ... more code ... // #enddocregion inner-region ... yet more code ... /// #enddocregion ```

The `src/app/app.module.ts` file has a good example of a nested region.

#### Combining fragments You can combine several fragments from the same file into a single code snippet by defining multiple _#docregions_ with the _same region name_. Examine the `src/app/app.component.ts` file which defines two nested _#docregions_. The inner, `class-skeleton` region appears twice, once to capture the code that opens the class definition and once to capture the code that closes the class definition. // #docplaster ... // #docregion class, class-skeleton export class AppComponent { // #enddocregion class-skeleton title = 'Authors Style Guide Sample'; heroes = HEROES; selectedHero: Hero; onSelect(hero: Hero): void { this.selectedHero = hero; } // #docregion class-skeleton } // #enddocregion class, class-skeleton Here's are the two corresponding code snippets displayed side-by-side.

Some observations: * The `#docplaster` at the top is another bit of code snippet markup. It tells the processor how to join the fragments into a single snippet. In this example, we tell the processor to put the fragments together without anything in between - without any "plaster". Most sample files define this _empty plaster_. If we neglected to add, `#docplaster`, the processor would insert the _default_ plaster - an ellipsis comment - between the fragments. Try removing the `#docplaster` comment yourself to see the effect. * One `#docregion` comment mentions **_two_** region names as does an `#enddocregion` comment. This is a convenient way to start (or stop) multiple regions on the same code line. You could have put these comments on separate lines and many authors prefer to do so. #### JSON files Code snippet markup is not supported for JSON files because comments are forbidden in JSON files. You can display an entire JSON file by referring to it in the `src` attribute. But you can't display JSON fragments because you can't add `#docregion` tags to the file. If the JSON file is too big, you could copy the nodes-of-interest into markdown backticks. Unfortunately, it's easy to mistakenly create invalid JSON that way. The preferred way is to create a JSON partial file with the fragment you want to display. You can't test this partial file and you'll never use it in the application. But at least your IDE can confirm that it is syntactically correct. Here's an example that excerpts certain scripts from `package.json` into a partial file named `package.1.json`. ```html ``` #### Partial file naming Many guides tell a story. In that story, the app evolves incrementally, often with simplistic or incomplete code along the way. To tell that story in code, you'll often need to create partial files or intermediate versions of the final source code file with fragments of code that don't appear in the final app. Such partial and intermediate files need their own names. Follow the doc sample naming convention. Add a number before the file extension as illustrated here: ```html package.1.json app.component.1.ts app.component.2.ts ``` You'll find many such files among the samples in the Angular documentation. Remember to exclude these files from stackblitz by listing them in the `stackblitz.json` as illustrated here. {@a live-examples} ## Live examples By adding `` to the page you generate links that run sample code in the Stackblitz live coding environment and download that code to the reader's file system. Live examples (AKA "stackblitz") are defined by one or more `stackblitz.json` files in the root of a code sample folder. Each sample folder usually has a single unnamed definition file, the default `stackblitz.json`.

You can create additional, named definition files in the form `name.stackblitz.json`. See `content/examples/testing` for examples. The schema for a `stackblitz.json` hasn't been documented yet but looking at the `stackblitz.json` files in the example folders should tell you most of what you need to know.

Adding `` to the page generates the two default links. 1. a link to the Stackblitz defined by the default `stackblitz.json` file located in the code sample folder with the same name as the guide page. 2. a link that downloads that sample. Clicking the first link opens the code sample in a new browser tab in the "embedded Stackblitz" style. You can change the appearance and behavior of the live example with attributes and classes.

Custom label and tooltip

Give the live example anchor a custom label and tooltip by setting the `title` attribute. ```html ``` You can achieve the same effect by putting the label between the `` tags: Live example with content label ```html Live example with content label ```

Live example from another guide

To link to a Stackblitz in a folder whose name is not the same as the current guide page, set the `name` attribute to the name of that folder. Live Example from the Router guide ```html Live Example from the Router guide ```

Live Example for named Stackblitz

To link to a Stackblitz defined by a named `stackblitz.json` file, set the `stackblitz` attribute. The following example links to the Stackblitz defined by `second.stackblitz.json` in the current guide's directory. ```html ```

Live Example without download

To skip the download link, add the `noDownload` attribute. Just the Stackblitz ```html Just the Stackblitz ```

Live Example with download-only

To skip the live Stackblitz link and only link to the download, add the `downloadOnly` attribute. Download only ```html Download only ```

Embedded live example

By default, a live example link opens a Stackblitz in a separate browser tab. You can embed the Stackblitz within the guide page itself by adding the `embedded` attribute. For performance reasons, the Stackblitz does not start right away. The reader sees an image instead. Clicking the image starts the sometimes-slow process of launching the embedded Stackblitz within an iframe on the page. You usually replace the default Stackblitz image with a custom image that better represents the sample. Store that image in the `content/images` directory in a folder with a name matching the corresponding example folder. Here's an embedded live example for this guide. It has a custom image created from a snapshot of the running app, overlayed with `content/images/Stackblitz/unused/click-to-run.png`. ```html ``` {@a anchors} ## Anchors Every section header tag is also an anchor point. Another guide page could add a link to this section by writing:

See the ["Anchors"](guide/docs-style-guide#anchors "Style Guide - Anchors") section for details.

```html

See the ["Anchors"](guide/docs-style-guide#anchors "Style Guide - Anchors") section for details.

``` When navigating within the page, you can omit the page URL when specifying the link that [scrolls up](#anchors "Anchors") to the beginning of this section. ```html ... the link that [scrolls up](#anchors "Anchors") to ... ``` {@a ugly-anchors} #### Ugly, long section header anchors It is often a good idea to *lock-in* a good anchor name. Sometimes the section header text makes for an unattractive anchor. [This one](#ugly-long-section-header-anchors) is pretty bad. ```html [This one](#ugly-long-section-header-anchors) is pretty bad. ``` The greater danger is that **a future rewording of the header text would break** a link to this section. For these reasons, it is often wise to add a custom anchor explicitly, just above the heading or text to which it applies, using the special `{@a name}` syntax like this. {@a ugly-anchors} #### Ugly, long section header anchors Now [link to that custom anchor name](#ugly-anchors) as you did before. ```html Now [link to that custom anchor name](#ugly-anchors) as you did before. ```

Alternatively, you can use the HTML `` tag. If you do, be sure to set the `id` attribute - not the `name` attribute! The docs generator will not convert the `name` to the proper link URL. ```html ## Anchors ```

## Alerts Alerts draw attention to important points. Alerts should not be used for multi-line content (use callouts insteads) or stacked on top of each other. Note that the content of an alert is indented to the right by two spaces.

A critical alert.

An important alert.

A helpful, informational alert.

Here is the markup for these alerts. ```html

A critical alert.

An important alert.

A helpful, informational alert.

``` Alerts are meant to grab the user's attention and should be used sparingly. They are not for casual asides or commentary. Use [subsections](#subsections "subsections") for commentary. ## Callouts Callouts (like alerts) are meant to draw attention to important points. Use a callout when you want a riveting header and multi-line content.

A critical point

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

An important point

**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 helpful point

Here is the markup for the first of these callouts. ```html

A critical point

``` Notice that * the callout header text is forced to all upper case. * the callout body can be written in markdown. * a blank line separates the `` tag from the markdown content. Callouts are meant to grab the user's attention. They are not for casual asides. Please use them sparingly. ## Trees Trees can represent hierarchical data.

sample-dir

src

app

app.component.ts

app.module.ts

styles.css

tsconfig.json

node_modules ...

package.json

Here is the markup for this file tree. ```html

sample-dir

src

app

app.component.ts

app.module.ts

styles.css

tsconfig.json

node_modules ...

package.json

``` ## Tables Use HTML tables to present tabular data.

Framework	Task	Speed
`AngularJS`	Routing	Fast
`Angular v2`	Routing	Faster
`Angular v4`	Routing	Fastest :)

Here is the markup for this table. ```html

Framework	Task	Speed
`AngularJS`	Routing	Fast
`Angular v2`	Routing	Faster
`Angular v4`	Routing	Fastest :)

``` ## Images

Image location

Store images in the `content/images` directory in a folder with the same URL as the guide page. Images for this "Authors Style Guide" page belong in the `content/images/guide/docs-style-guide` folder. Angular doc generation copies these image folders to the _runtime_ location, `generated/images`. Set the image `src` attribute to begin in _that_ directory. Here's the `src` attribute for the "flying hero" image belonging to this page. ``` src="generated/images/guide/docs-style-guide/flying-hero.png" ```

Use the HTML <img> tag

**Do not use the markdown image syntax, \!\[\.\.\.\]\(\.\.\.\).** Images should be specified in an `` tag. For accessibility, always set the `alt` attribute with a meaningful description of the image. You should nest the `` tag within a `

`. ```html # Authors Style Guide ``` **Only one title (`

Main section heading

` HTML tag. The main section heading should be followed by a blank line and then the content for that heading. ```html ## Sections A typical document is divided into sections. ```

Secondary section heading

`) and secondary (`