angular-cn/aio/content/guide/docs-style-guide.md

@title
Authors Style Guide

@intro
Style Guide for Angular Authors

@description



This guide covers design and layout patterns for documentation for Angular.  The patterns should be followed by Authors contributing to this documentation.

Throughout this guide, patterns are illustrated by first showing a working example and then presenting working code for that example.

## Basic Layout

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


## Main Section Title

Main section titles should preceeded by ##.  This is equvalent to the h2 HTML tag.  Content can start on the next line.

## Sub Section Title

The content in any sub-section is related to the main section content and _falls within_ the main section. Any sub-section title should preceeded by ###.  This is equivalent to the h3 HTML tag.  Content can start on the next line.

## Additional Sub Section Information

To present information to the user that may require redirection to other pages, internal or external to the docs, you can use class 'l-sub-section'.  Here is an example of such a sub-section.

<div class="l-sub-section">



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


</div>

The code for this is here.
```html
<div class="l-sub-section">


  You'll learn about more sytles for live examples in the [section below](guide/docs-style-guide#section-LiveExamples).


</div>
```


## Table of Contents

The table of contents (TOC) is automatically generated by looking at section titles and sub-section titles.  By default the TOC is two levels deep, that is, it displays only the section and sub-section titles.

To exclude a section or sub-section title from the TOC, use a class called 'no-toc'.  This class must be used in conjunction with HTML heading tags.  Titles displayed using Markdown heading hash tags cannot be excluded.   

### Example
```html
<h3 class="no-toc">

Not for our TOC

</h3>
```

## Left-hand Side Navigation

When you create the Markdown file for your guide, and include it at the appropriate location in navigation.json, you should see the title of your guide displayed in the navigation panel on the left hand side of the docs.  You can make further modifications to navigation.json to include any sub-chapters you may have.

## Code Examples

Code examples cn be used to provide code listings.  This code can be displayed inline or pulled from files.  Code examples allow you to display code with line numbers, from various programming languages, display in tabbed interfaces and such.  Below are a few examples of how you can add/customize code examples in a page.

###  Code-Example Attributes 

* path: a file in the content/examples folder
* title: seen in the header
* region: name of a docregion
* language: specify only for inline examples. Values can be javascript, html, css, typescript, json, sh or any other language that you will use in your Angular application.
* linenums: true, false, for example linenums:4 to speficy that the starting line is 4.  When not specified, line numbers are displayed when there are 10 or more lines of code  
* format: nocode, linenums??
* class: no-box, code-shell, avoid

### 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 Typescript, HTML, Javascript and CSS files.

Clearly there also needs to be some mechanism for including fragments of these files into the Markdown generated HTML. By convention all of the 'testable' examples within this repository should be created within the content/examples folder.

#### A Basic Code-example

Code-example displays code or content exactly as entered in a code-example.

<code-example>
  localhost:3000/hero/15
  localhost:3004/hero/again
</code-example>
```html
<code-example>
  localhost:3000/hero/15
  localhost:3004/hero/again
</code-example>
```

#### Example:

<code-example path="toh-pt1/src/index.html" linenums="true" title="src/index.html"></code-example>
The code will read the content/examples/toh-pt1/src/index.html file and include it with the heading 'src/index.html'. Note that the file will be properly escaped and color coded according to the extension on the file (html in this case).
```html
<code-example path="toh-pt1/src/index.html" linenums="true" title="src/index.html">
</code-example>
```


#### Example of a command to be entered in a command window
<code-example language="sh" class="code-shell">
  npm start
</code-example>
```html
<code-example language="sh" class="code-shell">
  npm start
</code-example>
```


#### Example of code to be avoided
<code-example class="avoid" title="hero-details.component.ts (Avoid)">
  &lt;hero-details <em>nghost-pmm-5&gt;
    &lt;h2 </em>ngcontent-pmm-5&gt;Mister Fantastic&lt;/h2&gt;
    &lt;hero-team <em>ngcontent-pmm-5 </em>nghost-pmm-6&gt;
      &lt;h3 _ngcontent-pmm-6&gt;Losing Team&lt;/h3&gt;
    &lt;/hero-team&gt;
  &lt;/hero-details&gt;
</code-example>
```html
<code-example class="avoid" title="hero-details.component.ts (Avoid)">
  <hero-details <em>nghost-pmm-5>
    <h2> </em>ngcontent-pmm-5>Mister Fantastic</h2>
    <hero-team> <em>ngcontent-pmm-5 </em>nghost-pmm-6>
      <h3> _ngcontent-pmm-6>Losing Team</h3>
    </hero-team>
  </hero-details>
</code-example>
```


#### Example of an HTML backticked code block

Backticked code blocks can be used to enclose HTML code without using escape characters.

```html
  <hero-details>
    <h2>Mister Fantastic</h2>
    <hero-team>
      <h3>Losing Team</h3>
    </hero-team>
  </hero-details>
```
<code-example language="html">
```html
  &lt;hero-details&gt;
    &lt;h2&gt;Mister Fantastic&lt;/h2&gt;
    &lt;hero-team&gt;
      &lt;h3&gt;Losing Team&lt;/h3&gt;
    &lt;/hero-team&gt;
  &lt;/hero-details&gt;
```
</code-example>

There is Code-tabs and Code-pane that provides the same service but for multiple examples within a tabbed interface.

### Code-tabs Attributes

* linenums: display line numbers in the code in all tabs

### Code-pane Attributes

* path: a file in the content/examples folder
* title: seen in the header
* linenums: display line numbers in the code in this tab

#### Example:

This example uses the source code for a small application that bundles with Webpack techniques.  This will create three tabs, each with its own title and appropriately color coded.  By default, line numbers are shown.  Line number display can be specified using the linenums attribute at the code tab or code pane level.  The example below shows us how to display line numbers in just one code pane. 

<code-tabs>
  <code-pane title="src/index.html" path="webpack/src/index.html">
  </code-pane>
  <code-pane title="src/tsconfig.json" path="webpack/src/tsconfig.1.json">
  </code-pane>
  <code-pane title="src/main.ts" path="webpack/src/main.ts">
  </code-pane>
  <code-pane title="src/assets/css/styles.css" path="webpack/src/assets/css/styles.css">
  </code-pane>
</code-tabs>

The code below will create multiple tabs, each with its own title and appropriately color coded.

```html
<code-tabs linenums="false">
  <code-pane title="src/index.html" path="webpack/src/index.html">
  </code-pane>
  <code-pane title="src/tsconfig.json" path="webpack/src/tsconfig.json" linenums="true">
  </code-pane>
  <code-pane title="src/main.ts" path="webpack/src/main.ts" linenums="true">
  </code-pane>
  <code-pane title="src/assets/css/styles.css" path="webpack/src/assets/css/styles.css">
  </code-pane>
</code-tabs>
```


### Marking up an example file for use by code-example

To mark any part of a file, add a single comment line in the line above the area to be marked.  The comment should contain the string #docregion. Optionally, a second string can follow.  The second string is the 'name' of the region. 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.  Further, docregions can be nested.

<div class="alert is-important">

Docregions are not supported in JSON

</div>

#### Example of a nested docregion:
<code-example language="html">
// #docregion export-AppComponent
export class AppComponent {
  title = 'Tour of Heroes';
  heroes = HEROES;
  // #docregion selected-hero
  selectedHero: Hero;
  // #enddocregion selected-hero

  // #docregion on-select, onSelect-parameters
  onSelect(hero: Hero): void {
    this.selectedHero = hero;
  }
  // #enddocregion on-select
}
// #enddocregion export-AppComponent

 &lt;code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero"&gt;
&lt;/code-example&gt;

&lt;code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters"&gt;
&lt;/code-example&gt; 
</code-example>

<code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero">
</code-example>

<code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters">
</code-example>

HTML files can also contain docregions:
```html
<!-- #docregion -->
...
<script src="app.js"></script>
...
```

as can CSS files:
```html
/* #docregion center-global */
.center-global {
  max-width: 1020px;
  margin: 0 auto;
}
```


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

Code can be included directly inline, that is, not be fetched from some external file.

#### Example
```html
code-example(format="linenums" language="javascript").
  //SOME CODE
```

#### Specify starting line number
```html
code-example(language="html" format="linenums:4")
  var title = "This starts on line four";
```


{@a section-LiveExamples}
## Live Examples

Here is how we do live examples.  All examples here will point to TOH-6 for convenience.

### Plain Live Example
```html
<live-example></live-example>
```

A plain live example looks like this: <live-example name="toh-pt6"></live-example>

### Live Example with Title Attribute
```html
<live-example title="Live Example with User Desired Title"></live-example>
```

### Live Example with Body like seen in router, same exact result as attrib title
```html
<live-example>Live Example Flesh & Blood</live-example>
```

### Live Example from Another Guide
```html
<live-example name="router">Live Example from the Router guide</live-example>
```

### Live Example other than Default for Guide
```html
<live-example plnkr="second-live-example"></live-example>
```

### Live Example Without Download
```html
<live-example noDownload></live-example>
```

### Live Example with only Download
```html
<live-example downloadOnly></live-example>
```

### Live Example with Embedded Plunkers
Embedded Plunkrs have default image.  img allows you to override the deafult image.  
```html
<live-example embedded img="guide/router/img1.png"></live-example>
```

{@a section-Anchors}
## Anchors

To mark a location that a reader should reach when they click on an anchor, insert the tag below at that location. 
<code-example language="html">
    I have been marked using {@ section-Anchors} `{@a section-Anchors}`
</code-example>

To use this anchor, replace alternative text below with text that will be visible to the reader and that the reader will click on.  Replace path-to-page with the relative path to the page that has the location that the reader should reach.
```html
[alternative text] (path-to-page/dir-of-page/#section-Anchors)
```

### Example
[Click this] (guide/docs-style-guide/#section-Anchors) to reach the beginning of this section on Anchors.


## Alerts

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

<div class="l-sub-section">

### Adding an Alert

<div class="alert is-critical">
A very critical alert.
</div>

<div class="alert is-important">
A very important alert.
</div>

<div class="alert is-helpful">
A very helpful alert.
</div>

</div>

Here is sample code to generate alerts.
```html
<div class="alert is-critical">
A very critical alert.
</div>

<div class="alert is-important">
A very important alert.
</div>

<div class="alert is-helpful">
A very helpful alert.
</div>
```


## 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.

<div class="l-sub-section">

<div class="callout is-critical">

<header>
A CRITICAL TITLE
</header>

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

</div>

<div class="callout is-important">

<header>
A VERY IMPORTANT TITLE
</header>

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

</div>

<div class="callout is-helpful">

<header>
A VERY HELPFUL TITLE
</header>

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

</div>

</div>

Here is sample code to generate important callouts.
```html
<div class="callout is-important">

<header>
A VERY IMPORTANT TITLE
</header>

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

</div>
```



## Trees

Trees can be used to represent heirarchial data.  Here is an example.

<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>

Here is the code for this tree

```html
<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>
```


## Tables

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

<div class="l-sub-section">

### Adding a Table

<style>
  td, th {vertical-align: top}
</style>

<table>

  <tr>

    <th>
      Framework
    </th>

    <th>
      Task
    </th>
 
    <th>
      Speed
    </th>

 </tr>

  <tr>

    <td>
      <code>AngularJS</code>
    </td>

    <td>
      Routing 
    </td>

    <td>
      <code>Fast</code>
    </td>

</tr>

  <tr>

    <td>
      <code>Angular 2</code>
    </td>

    <td>
      Routing 
    </td>

    <td>
      <code>Faster</code>
    </td>

</tr>

<tr>

    <td>
      <code>Angular 4</code>
    </td>

    <td>
      Routing 
    </td>

    <td>
      <code>Fastest :)</code>
    </td>

</tr>


</table>

To-do: format below closer to what is seen in old guide

```html
table
    tr
        th Framework
        th Task
        th Speed
    tr
        td AngularJS
        td Routing
        td fast
```

</div>

## Images

### Using Images

HTML should be used to declare images in the docs. Do not use the markdown \!\[\.\.\.\]\(\.\.\.\) shorthand.

The HTML to use is an &lt;img src="..." alt="..."&gt; tag. You must supply a src attribute that is relative to the base path; and you should provide an alt attribute describing the image for accessibility. _Note that Image tags do not have a closing tag._


### Image Size

The doc generation process will read the image dimensions and automatically add width and height attributes to the img tag. If you want to control the size of the image then you should supply your own width and height images.

Images should not be wider than 700px otherwise they may overflow the width of the document in certain viewports. If you wish to have a larger image then provide a link to the actual image that the user can click on to see the larger images separately.


### Image Formatting

There are three types of images that you can put in docs: inline, floating and standalone.

#### Inline Images

To create an inline image, simply place the img tag in the content where you want the image to appear. For example:

```html
The image here <img src="..." alt="..."> is visible inline in the text.

```

#### Floating Images

You can cause an image to float to the left or right of the text by applying the class="left" or class="right" attributes respectively.
    
```html
<img src="..." alt="..." class="left">This text will wrap around the to the right of this floating image.
```

All headings and code-examples will automatically clear a floating image. If you need to force a piece of text to clear a floating image then you can use the following snippet:

```html
<br class="clear">
```

Finally, if you have floating images inside alerts or sub-sections then it is a good idea to apply the clear-fix class to the div to ensure that the image doesn't overflow its container. For example:

```html
<div class="l-sub-section clear-fix">

  <img class="right" src="..." alt="...">
  Some **markdown** formatted text.

</div>

```

#### Standalone Images

Some images should stand alone from the text. You do this by wrapping the img tag in a figure tag. This causes the image to get additional styling, such as a rounded border and shadow. The text will not flow around this image but will stop before the image and start again afterword. For example:

```html
Some paragraph preceding the image.
<figure>
  <img src="" alt="">
</figure>

```