Angular documentation style guidelink

This style guide covers the standards for writing Angular documentation on angular.io. These standards ensure consistency in writing style, Markdown conventions, and code snippets.

Prerequisiteslink

Before contributing to the Angular documentation, it is helpful if you are familiar with the following:

• git: for an introduction, see GitHub's Git Handbook
• GitHub: for an introduction, see GitHub's Hello World
• Markdown: see GitHub's Mastering Markdown
• Angular coding style: see the Angular Style Guide
• Google writing style: The Google Developer Documentation Style Guide is a comprehensive resource that this Angular documentation style guide builds upon.

Kinds of Angular documentationlink

The categories of Angular documentation include:

• Guides: much of what's in the documentation section of angular.io. Guides walk the reader step-by-step through tasks to demonstrate concepts and are often accompanied by a working example. These include Getting Started, Tour of Heroes, and pages about Forms, Dependency Injection, and HttpClient. Contributing members of the community and Angular team members maintain this documentation in Markdown.
• API documentation: reference documents for the Angular Application Programming Interface, or API. These are more succinct than guides and serve as a reference for Angular features. They are especially helpful for people already acquainted with Angular concepts. The angular.io infrastructure generates these documents from source code and comments that contributors edit.
• CLI documentation: the angular.io infrastructure generates these documents from CLI source code.

Markdown and HTMLlink

While the Angular guides are Markdown files, there are some sections within the guides that use HTML.

Notice the required blank line after the opening <div> in the following example:

      
        content_copy
      
      <div class="alert is-helpful">

  **Always** follow every opening and closing HTML tag with _a blank line_.

</div>
    

It is customary but not required to precede the closing HTML tag with a blank line as well.

Titlelink

Every guide document must have a title, and it should appear at the top of the page.

Begin the title with the Markdown # character, which renders as an <h1> in the browser.

      
        content_copy
      
      # Angular documentation style guide
    

A document can have only one <h1>.

Title text should be in Sentence case, which means the first word is capitalized and all other words are lower case. Technical terms that are always capitalized, like "Angular", are the exception.

      
        content_copy
      
      # Deprecation policy in Angular
    

Always follow the title with at least one blank line.

The corresponding text in the left nav is in Title Case, which means that you use capital letters to start the first words and all principal words. Use lower case letters for secondary words such as "in", "of", and "the". You can also shorten the nav title to fit in the column.

Sectionslink

A typical document has sections.

All section headings are in Sentence case, which means the first word is capitalized and all other words are lower case.

Always follow a section heading with at least one blank line.

Main section headinglink

There are usually one or more main sections that may be further divided into secondary sections.

Begin a main section heading with the Markdown ## characters, which renders as an <h2> in the browser.

Follow main section headings with a blank line and then the content for that heading as in the following example:

      
        content_copy
      
      ## Main section heading

Content after a blank line.
    

Secondary section headinglink

A secondary section heading is related to a main heading and falls textually within the bounds of that main heading.

Begin a secondary heading with the Markdown ### characters, which renders as an <h3> in the browser.

Follow a secondary heading by a blank line and then the content for that heading as in the following example:

      
        content_copy
      
      ### Secondary section heading

Content after a blank line.
    

Additional section headingslink

While you can use additional section headings, the Table-of-contents (TOC) generator only shows <h2> and <h3> headings in the TOC on the right of the page.

      
        content_copy
      
      #### The TOC won't display this

Content after a blank line.
    

Table of contentslink

Most pages display a table of contents or TOC. The TOC appears in the right panel when the viewport is wide. When narrow, the TOC appears in a collapsible region near the top of the page.

You don't need to create your own TOC by hand because the TOC generator creates one automatically from the page's <h2> and <h3> headers.

To exclude a heading from the TOC, create the heading as an <h2> or <h3> element with a class called 'no-toc'.

      
        content_copy
      
      <h3 class="no-toc">

This heading is not displayed in the TOC

</h3>
    

You can turn off TOC generation for the entire page by writing the title with an <h1> tag and the no-toc class.

      
        content_copy
      
      <h1 class="no-toc">

A guide without a TOC

</h1>
    

Navigationlink

To generate the navigation links at the top, left, and bottom of the screen, use the JSON configuration file, content/navigation.json.

For a new guide page, edit 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.

      
        content_copy
      
      {
  "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 as in the following example:

      
        content_copy
      
      {
  "url": "guide/docs-style-guide",
  "title": "Doc authors style guide",
  "tooltip": "Style guide for documentation authors.",
},
    

A navigation node has the following properties:

• url: the URL of the guide page, which is an 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, which is a header node only.

• hidden: defined and set true if this is a guide page that should not be displayed in the navigation panel.

Code snippetslink

Angular.io has a custom framework that enables authors to include code snippets directly from working example apps that are automatically tested as part of documentation builds.

In addition to working code snippets, example code can include terminal commands, 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 component or as a tabbed collection with the code-tabs component.

When to use code fontlink

You can display a minimal, inline code snippet with the Markdown backtick syntax. Use a single backtick on either side of a term when referring to code or the name of a file in a sentence. The following are some examples:

• In the app.component.ts, add a logger() method.
• The name property is Sally.
• Add the component class name to the declarations array.

The Markdown is as follows:

      
        content_copy
      
      * In the `app.component.ts`, add a `logger()` method.
* The <code class="no-auto-link">item</code> property is `true`.
* Add the component class name to the `declarations` array.
    

Auto-linking in code snippetslink

In certain cases, when you apply backticks around a term, it may auto-link to the API documentation. If you do not intend the term to be a link, use the following syntax:

      
        content_copy
      
      The <code class="no-auto-link">item</code> property is `true`.
    

Hard-coded snippetslink

Ideally, you should source code snippets from working sample code, though there are times when an inline snippet is necessary.

For terminal input and output, place the content between <code-example> tags and set the language attribute to sh as in this example:

      
        content_copy
      
      npm start
    

      
        content_copy
      
      <code-example language="sh">

  npm start

</code-example>
    

Inline, hard-coded snippets like this one are not testable and, therefore, 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.

In all other cases, code snippets should be generated automatically from tested code samples.

For hypothetical examples such as illustrations of configuration options in a JSON file, use the <code-example> tag with the header attribute to identify the context.

Compilable example appslink

One of the Angular documentation design goals is that guide page code snippets be examples of working code.

Authors meet this goal by displaying code snippets directly from working sample apps, written specifically for these guide pages.

Find sample apps in sub-folders of the content/examples directory of the angular/angular repository. An example folder name is often the same as the guide page it supports.

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.

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 <code-example> attributes.

Displaying an entire code filelink

This Angular documentation style guide that you are currently reading has its own example application, located in the content/examples/docs-style-guide folder.

The following <code-example> displays the sample's app.module.ts:

      
        content_copy
      
      import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { FormsModule } from '@angular/forms';

import { AppComponent } from './app.component';

@NgModule({
  imports:      [ BrowserModule, FormsModule ],
  declarations: [ AppComponent ],
  bootstrap:    [ AppComponent ]
})
export class AppModule { }
    

The following markup produces that snippet:

      
        content_copy
      
      <code-example path="docs-style-guide/src/app/app.module.ts" header="src/app/app.module.ts">
</code-example>
    

The path attribute identifies the snippet's source file at the example app folder's location within content/examples. In this example, that path is docs-style-guide/src/app/app.module.ts.

The header tells the reader where to find the file. Following convention, set the header attribute to the file's location within the example app's root folder.

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

      
        content_copy
      
      # my-guide
!my-guide/src/something.js
!my-guide/more-javascript*.js
    

Displaying part of a code filelink

To include a snippet of code within a sample code file, rather than the entire file, use the <code-example> region attribute. The following example focuses on the AppModule class and its @NgModule() metadata:

      
        content_copy
      
      @NgModule({
  imports:      [ BrowserModule, FormsModule ],
  declarations: [ AppComponent ],
  bootstrap:    [ AppComponent ]
})
export class AppModule { }
    

To render the above example, the HTML in the Markdown file is as follows:

      
        content_copy
      
      <code-example
  path="docs-style-guide/src/app/app.module.ts"
  region="class">
</code-example>
    

The path points to the file, just as in examples that render the entire file. The region attribute specifies a portion of the source file delineated by an opening #docregion and a closing #enddocregion.

You can see the class #docregion in the source file below. Notice the commented lines #docregion and #enddocregion in content/examples/docs-style-guide/src/app/app.module.ts with the name class.

      
        content_copy
      
      import { NgModule }      from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { FormsModule }   from '@angular/forms';

import { AppComponent }  from './app.component';

// #docregion class
@NgModule({
  imports:      [ BrowserModule, FormsModule ],
  declarations: [ AppComponent ],
  bootstrap:    [ AppComponent ]
})
export class AppModule { }
// #enddocregion class
    

The opening and ending #docregion lines designate any lines of code between them as being included in the code snippet. This is why the import statements outside of the class #docregion are not in the code snippet.

For more information on how to prepare example app files for use in guides, see Source code markup.

Code snippet optionslink

Specify the <code-example> output with the following attributes:

• path: the path to the file in the content/examples folder.

• header: the header of the code listing. This is the title of the code snippet and can include the path and extra information such as whether the snippet is an excerpt.

• region: displays the source file fragment with that region name; regions are identified by #docregion markup in the source file. See Displaying a code snippet.

• linenums: value may be true, false, or a number. The default is false, which means that the browser displays no line numbers. The number option starts line numbering at the given value. For example, linenums=4 sets the starting line number to 4.

• class: code snippets can be styled with the CSS classes no-box and avoid.

• hideCopy: hides the copy button.

• language: the source code language such as javascript, html, css, typescript, json, or sh. This attribute only applies to hard-coded examples.

Displaying bad codelink

Occasionally, you want to display an example of less than ideal code or design, such as with avoid examples in the Angular Style Guide. Because it is possible for readers to copy and paste examples of inferior code in their own applications, try to minimize use of such code.

In cases where you need unacceptable examples, you can set the class to avoid or have the word avoid in the filename of the source file. By putting the word avoid in the filename or path, the documentation generator automatically adds the avoid class to the <code-example>. Either of these options frames the code snippet in bright red to grab the reader's attention.

Here's the markup for an "avoid" example in the Angular Style Guide that uses the word avoid in the path name:

      
        content_copy
      
      <code-example
  path="styleguide/src/05-03/app/heroes/shared/hero-button/hero-button.component.avoid.ts"
  region="example"
  header="app/heroes/hero-button/hero-button.component.ts">
</code-example>
    

Having the word "avoid" in the file name causes the browser to render the code snippet with a red header and border:

      
        content_copy
      
      /* avoid */

@Component({
  selector: '[tohHeroButton]',
  templateUrl: './hero-button.component.html'
})
export class HeroButtonComponent {}
    

Alternatively, the HTML could include the avoid class as in the following:

      
        content_copy
      
      <code-example
  path="docs-style-guide/src/app/not-great.component.ts"
  header="docs-style-guide/src/app/not-great.component.ts"
  region="not-great"
  class="avoid">
</code-example>
    

Explicitly applying the class avoid causes the same result of a red header and red border:

      
        content_copy
      
      export class NotGreatComponent {

  buggyFunction() {
    // things could be better here...
  }
}
    

Code Tabslink

Code tabs display code much like code-examples with the added advantage of displaying multiple code samples within a tabbed interface. Each tab displays code using a code-pane.

code-tabs attributeslink

• linenums: The value can be true, false, or a number indicating the starting line number. The default is false.

code-pane attributeslink

• path: a file in the content/examples folder
• header: what displays 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. The default is false.

The following example displays multiple code tabs, each with its own header. It demonstrates showing line numbers in <code-tabs> and <code-pane>.

      
        content_copy
      
      
<h1>{{title}}</h1>
<h2>My Heroes</h2>
<ul class="heroes">
  <li *ngFor="let hero of heroes"
    [class.selected]="hero === selectedHero"
    (click)="onSelect(hero)">
    <span class="badge">{{hero.id}}</span> {{hero.name}}
  </li>
</ul>
<div *ngIf="selectedHero">
  <h2>{{selectedHero.name}} details!</h2>
  <div><label>id: </label>{{selectedHero.id}}</div>
  <div>
    <label>name: </label>
    <input [(ngModel)]="selectedHero.name" placeholder="name"/>
  </div>
</div>
    

The linenums attribute set to true on <code-tabs> explicitly enables numbering for all panes. However, the linenums attribute set to false in the second <code-pane> disables line numbering only for itself.

      
        content_copy
      
      <code-tabs linenums="true">
  <code-pane
    header="app.component.html"
    path="docs-style-guide/src/app/app.component.html">
  </code-pane>
  <code-pane
    header="app.component.ts"
    path="docs-style-guide/src/app/app.component.ts"
    linenums="false">
  </code-pane>
  <code-pane
    header="app.component.css (heroes)"
    path="docs-style-guide/src/app/app.component.css"
    region="heroes">
  </code-pane>
  <code-pane
    header="package.json (scripts)"
    path="docs-style-guide/package.1.json">
  </code-pane>
</code-tabs>
    

Preparing source code for code snippetslink

To display <code-example> and <code-tabs> snippets, add code snippet markup to sample source code files.

Code snippet markup is always in the form of a comment. The default #docregion markup for a TypeScript or JavaScript file is as follows:

      
        content_copy
      
      // #docregion
... some TypeScript or JavaScript code ...
// #enddocregion
    

      
        content_copy
      
      <!-- #docregion -->
... some HTML ...
<!-- #enddocregion -->
    

      
        content_copy
      
      /* #docregion */
... some CSS ...
/* #enddocregion */
    

The documentation generation process erases these comments before displaying them in the documentation viewer, StackBlitz, and sample code downloads.

#docregionlink

Use #docregion in source files to mark code for use in <code-example> or <code-tabs> components.

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 following src/main.ts is a an example of a file with a single #docregion at the top of the file.

      
        content_copy
      
      import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic().bootstrapModule(AppModule);
    

As a result, the entire file is in the <code-example>.

Naming a #docregionlink

To display multiple snippets from different fragments within the same file, give each fragment its own #docregion name as follows, where your-region-name is a hyphenated lowercase string:

      
        content_copy
      
      // #docregion your-region-name
... some code ...
// #enddocregion your-region-name
    

Reference this region by name in the region attribute of the <code-example> or <code-pane> as follows:

      
        content_copy
      
      <code-example
  path="your-example-app/src/app/your-file.ts"
  region="your-region-name"></code-example>
    

Because the #docregion with no name is the default region, you do not need to set the region attribute when referring to the default #docregion.

Nesting a #docregionlink

Place a #docregion within another #docregion as in the following example with a nested inner-region:

      
        content_copy
      
      // #docregion
... some code ...
// #docregion inner-region
... more code ...
// #enddocregion inner-region
... yet more code ...
/// #enddocregion
    

Combining code fragmentslink

Combine several fragments from the same file into a single code snippet by defining multiple #docregion sections with the same region name. The following example defines two nested #docregion sections.

The inner region, class-skeleton, appears twice—once to capture the code that opens the class definition and a second time to capture the code that closes the class definition.

      
        content_copy
      
      // #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
    

The #docplaster marker tells the processor what text string to use—that is, the "plaster"—to join each of the fragments into a single snippet. Place the "plaster" text on the same line. For example, #docplaster --- would use --- as the "plaster" text. In the case of the previous file, the "plaster" text is empty so there will be nothing in between each fragment.

Without #docplaster, the processor inserts the default plaster—an ellipsis comment—between the fragments.

Here are the two corresponding code snippets for side-by-side comparison.

      
        content_copy
      
      export class AppComponent {
  title = 'Authors Style Guide Sample';
  heroes = HEROES;
  selectedHero: Hero;

  onSelect(hero: Hero): void {
    this.selectedHero = hero;
  }
}
    

The above example also demonstrates that one #docregion or #enddocregion comment can specify two region names, which is a convenient way to start or stop multiple regions on the same code line. Alternatively, you could put these comments on separate lines as in the following example:

      
        content_copy
      
      // #docplaster
...
// #docregion class
// #docregion 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
// #enddocregion class-skeleton
    

JSON fileslink

The <code-example> component cannot display portions of a JSON file because JSON forbids comments. However, you can display an entire JSON file by referencing it in the <code-example> src attribute.

For large JSON files, you could copy the nodes-of-interest into Markdown backticks, but as it's easy to mistakenly create invalid JSON that way, consider creating a JSON partial file with the fragment you want to display.

You can't test a partial file nor use it in the application, but at least your editor can confirm that it is syntactically correct. You can also store the partial file next to the original, so it is more likely that the author will remember to keep the two in sync.

Here's an example that excerpts certain scripts from package.json into a partial file named package.1.json.

      
        content_copy
      
      {
  "scripts": {
    "start": "concurrently \"npm run build:watch\" \"npm run serve\"",
    "test": "concurrently \"npm run build:watch\" \"karma start karma.conf.js\"",
    "lint": "tslint ./src/**/*.ts -t verbose"
  }
}
    

      
        content_copy
      
      <code-example path="docs-style-guide/package.1.json" header="package.json (selected scripts)"></code-example>
    

In some cases, it is preferable to use the name of the full file rather than the partial. In this case, the full file is package.json and the partial file is package.1.json. Since the focus is generally on the full file rather than the partial, using the name of the file the reader edits, in this example package.json, clarifies which file to work in.

Partial file naminglink

The step-by-step nature of the guides necessitate refactoring, which means there are code snippets that evolve through a guide.

Use partial files to demonstrate intermediate versions of the final source code with fragments of code that don't appear in the final app. The sample naming convention adds a number before the file extension, as follows:

      
        content_copy
      
      package.1.json
app.component.1.ts
app.component.2.ts
    

Remember to exclude these files from StackBlitz by listing them in the stackblitz.json as illustrated here:

      
        content_copy
      
      {
  "description": "Authors style guide",
  "files": [
    "!**/*.d.ts",
    "!**/*.js",
    "!**/*.[1,2,3].*"
  ],
  "tags": ["author", "style guide"]
}
    

Live exampleslink

Adding <live-example></live-example> to a page generates two default links:现场演练 / 下载范例.

The first is a link to the StackBlitz example, which the default stackblitz.json file defines. You can find the stackblitz.json file in the content/examples/example-app directory, where example-app is the sample application folder you're using for the guide.

By default, the documentation generator uses the name of the guide as the name of the example. So, if you're working on router.md, and use <live-example></live-example> in the document, the documentation generator looks for content/examples/router. Clicking this link opens the code sample on StackBlitz in a new browser tab.

The second link downloads the sample app.

Define live examples 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.

Live Example for named StackBlitzlink

You can create additional, named definition files in the form name.stackblitz.json. The Testing guide (aio/content/guide/testing.md) references a named StackBlitz file as follows:

      
        content_copy
      
      <live-example stackblitz="specs">Tests</live-example>
    

The stackblitz attribute value of specs refers to the examples/testing/specs.stackblitz.json file. If you were to leave out the stackblitz attribute, the default would be examples/testing/stackblitz.json.

Custom label and tooltiplink

Change the appearance and behavior of the live example with attributes and classes. The following example gives the live example anchor a custom label and tooltip by setting the title attribute:

      
        content_copy
      
      <live-example title="Live Example with title"></live-example>
    

The browser renders the following:

Live Example with title / 下载范例

You can achieve the same effect by putting the label between the <live-example> tags:

      
        content_copy
      
      <live-example>Live example with content label</live-example>
    

The browser renders the following:

Live example with content labelLive example with content label / 下载范例

Live example from another guidelink

To link to an example in a folder where the name is not the same as the current guide page, set the name attribute to the name of that folder.

For example, to include the Router guide example in this style guide, set the name attribute to router, that is, the name of the folder where that example resides.

      
        content_copy
      
      <live-example name="router">Live example from the Router guide</live-example>
    

Live example from the Router guideLive example from the Router guide / 下载范例

Live Example without downloadlink

To omit the download link, add the noDownload attribute.

      
        content_copy
      
      <live-example noDownload>Just the StackBlitz</live-example>
    

The browser renders the following:

Just the StackBlitzJust the StackBlitz

Live Example with download-onlylink

To omit the live StackBlitz link and only link to the download, add the downloadOnly attribute.

      
        content_copy
      
      <live-example downloadOnly>Download only</live-example>
    

The browser renders the following:

Download onlyDownload only

Embedded live examplelink

By default, a live example link opens a StackBlitz example in a separate browser tab. You can embed the StackBlitz example within the guide page by adding the embedded attribute.

For performance reasons, StackBlitz does not start right away. Instead, the <live-example> component renders an image. Clicking the image starts the process of launching the embedded StackBlitz within an <iframe>.

The following is an embedded <live-example> for this guide:

      
        content_copy
      
      <live-example embedded></live-example>
    

The browser renders the following <iframe> and a <p> with a link to download the example:

你还可以 下载这个例子。

Anchorslink

Every section header is also an anchor point. Another guide page could add a link to this "Anchors" section with the following:

      
        content_copy
      
      <div class="alert is-helpful">

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

</div>
    

The browser renders the following:

Notice that the above example includes a title of "Style Guide—Anchors". Use titles on anchors to create tooltips and improve UX.

When navigating within a page, you can omit the page URL when specifying the link that scrolls up to the beginning of this section, as in the following:

      
        content_copy
      
      ... the link that [scrolls up](#anchors "Anchors") to ...
    

Section header anchorslink

While the documentation generator automatically creates anchors for headers based on the header wording, titles can change, which can potentially break any links to that section.

To mitigate link breakage, add a custom anchor explicitly, just above the heading or text to which it applies, using the special syntax as follows:

      
        content_copy
      
      

#### Section header anchors
    

Then reference that anchor like this:

      
        content_copy
      
      This is a [link to that custom anchor name](#section-anchors).
    

The browser renders the following:

This is a link to that custom anchor name.

When editing a file, don't remove any anchors. If you change the document structure, you can move an existing anchor within that same doc without breaking a link. You can also add more anchors with more appropriate text.

      
        content_copy
      
      <a id="anchors"></a>

## Anchors
    

Alerts and calloutslink

Alerts and callouts present warnings, extra detail, or references to related topics.

An alert or callout should not contain anything essential to understanding the main content. Instructions or tutorial steps should be in the main body of a guide rather than in a subsection.

Alertslink

Alerts draw attention to short, important points. For multi-line content, see callouts.

Note that at least one blank line must follow both the opening and closing <div> tags. A blank line before the closing </div> is conventional but not required.

      
        content_copy
      
      <div class="alert is-helpful">

  See the [live examples](guide/docs-style-guide#live-examples "Live examples") section for more information.

</div>
    

There are three different levels for styling the alerts according to the importance of the content.

Use the following the alert class along with the appropriate is-helpful, is-important, or is-critical CSS class, as follows:

      
        content_copy
      
      <div class="alert is-helpful">

A helpful, informational alert.

</div>
    

      
        content_copy
      
      <div class="alert is-important">

An important alert.

</div>
    

      
        content_copy
      
      <div class="alert is-critical">

A critical alert.

</div>
    

The browser renders the following:

Calloutslink

Callouts, like alerts, highlight important points. Use a callout when you need a header and multi-line content.

If you have more than two paragraphs, consider creating a new page or making it part of the main content.

Callouts use the same styling levels as alerts.

Use the CSS class callout in conjunction with the appropriate is-helpful, is-important, or is-critical class. The following example uses the is-helpful class:

      
        content_copy
      
      <div class="callout is-helpful">

<header>A helpful or informational point</header>

  **A helpful note**. Use a helpful callout for information requiring explanation.
  Callouts are typically multi-line notes.
  They can also contain code snippets.

</div>
    

The browser renders the three styles as follows:

When using callouts, consider the following points:

• The callout header text style is uppercase.
• The header does not render in the table of contents.
• You can write the callout body in Markdown.
• A blank line separates the <header> tag from the Markdown content.
• Avoid using an <h2>, <h3>, <h4>, <h5>, or <h6>, as the CSS for callouts styles the <header> element.

Use callouts sparingly to grab the user's attention.

Treeslink

Use trees to represent hierarchical data such as directory structure.

Here is the markup for this file tree.

      
        content_copy
      
      <div class='filetree'>
    <div class='file'>
        sample-dir
    </div>
    <div class='children'>
        <div class='file'>
          src
        </div>
        <div class='children'>
            <div class='file'>
              app
            </div>
            <div class='children'>
                <div class='file'>
                  app.component.ts
                </div>
                <div class='file'>
                  app.module.ts
                </div>
            </div>
            <div class='file'>
              styles.css
            </div>
            <div class='file'>
              tsconfig.json
            </div>
        </div>
        <div class='file'>
          node_modules ...
        </div>
        <div class='file'>
          package.json
        </div>
    </div>
</div>
    

Tableslink

Use HTML tables to present tabular data.

The following is the markup for this table:

      
        content_copy
      
      <table>
  <tr>
    <th>Header Type</th>
    <th>Markdown</th>
    <th>Use</th>
  </tr>
  <tr>
    <td><code>&lt;h1&gt;</code></td>
    <td>#</td>
    <td>Title of page</td>
  </tr>
  <tr>
    <td><code>&lt;h2&gt;</code></td>
    <td>##</td>
    <!-- can use Markdown too; remember blank lines -->
    <td>

      **Second level headers**

    </td>
  </tr>
  <tr>
    <td><code>&lt;h3&gt;</code></td>
    <td>###</td>
    <td>

      **Third level headers**

    </td>
  </tr>
</table>
    

Imageslink

Store images in the content/images/guide directory in a folder with the same name as the guide page. Because Angular documentation generation copies these images to generated/images/guide/your-guide-directory, set the image src attribute to the runtime location of generated/images/guide/your-guide-directory.

For example, images for this "Angular documentation style guide" are in the content/images/guide/docs-style-guide folder, but the src attribute specifies the generated location.

The following is the src attribute for the "flying hero" image belonging to this guide:

      
        content_copy
      
      src="generated/images/guide/docs-style-guide/flying-hero.png"
    

Use the HTML <img> tag

Specify images using the <img> tag. Do not use the Markdown image syntax, .

For accessibility, always set the alt attribute with a meaningful description of the image.

Nest the <img> tag within a <div class="lightbox"> tag, which styles the image according to the documentation standard.

      
        content_copy
      
      <div class="lightbox">
  <img src="generated/images/guide/docs-style-guide/flying-hero.png" alt="flying hero">
</div>
    

Note that the HTML <img> element does not have a closing tag.

The browser renders the following:

Image captions and figure captionslink

A caption appears underneath the image as a concise and comprehensive summary of the image. Captions are optional unless you are using numbered figures, such as Figure 1, Figure 2, and so on. If you are using numbered figures in a page, follow the guidelines in Figure captions in the Google Developer Documentation Style Guide.

Image dimensionslink

The doc generator reads the image dimensions from an image file and adds width and height attributes to the <img> tag automatically.

To control the size of the image, supply your own width and height attributes.

Here's the "flying hero" markup with a 200px width:

      
        content_copy
      
      <div class="lightbox">
  <img src="generated/images/guide/docs-style-guide/flying-hero.png"
    alt="flying Angular hero"
    width="200">
</div>
    

The browser renders the following:

Wide imageslink

To prevent images overflowing their viewports, use image widths under 700px. To display a larger image, provide a link to the actual image that the user can click to see the full size image separately, as in this example of source-map-explorer output from the "Ahead-of-time Compilation" guide:

The following is the HTML for creating a link to the image:

      
        content_copy
      
      <a href="generated/images/guide/docs-style-guide/toh-pt6-bundle.png" title="Click to view larger image">
  <div class="lightbox">
    <img src="generated/images/guide/docs-style-guide/toh-pt6-bundle-700w.png" alt="toh-pt6-bundle" width="300px">
  </div>
</a>
    

Image compressionlink

For faster load times, always compress images. Consider using an image compression web site such as tinypng.

Floated imageslink

You can float the image to the left or right of text by applying the class="left" or class="right" attributes respectively. For example:

      
        content_copy
      
      <img src="generated/images/guide/docs-style-guide/flying-hero.png"
   alt="flying Angular hero"
   width="200"
   class="left">

This text wraps around to the right of the floating "flying hero" image.

Headings and code-examples automatically clear a floated image. If you need to force a piece of text to clear a floating image, add `<br class="clear">` where the text should break.

<br class="clear">
    

The browser renders the following:

This text wraps around to the right of the floating "flying hero" image.

Headings and <code-example> components automatically clear a floated image. To explicitly clear a floated image, add <br class="clear"> where the text should break.

Generally, you don't wrap a floated image in a <figure> element.

Floats within a subsectionlink

If you have a floated image inside an alert, callout, or a subsection, apply the clear-fix class to the <div> to ensure that the image doesn't overflow its container. For example:

      
        content_copy
      
      <div class="alert is-helpful clear-fix">

  <img src="generated/images/guide/docs-style-guide/flying-hero.png"
    alt="flying Angular hero"
    width="100"
    class="right">

  A subsection with **Markdown** formatted text.

</div>
    

The browser renders the following:

Help with documentation stylelink

For specific language and grammar usage, a word list, style, tone, and formatting recommendations, see the Google Developer Documentation Style Guide.

If you have any questions that this style guide doesn't answer or you would like to discuss documentation styles visit the Angular repo and file a documentation issue.