+ **Always** follow every opening and closing opening HTML tag with _a blank line_.
```
-Note that blank lines have been left within the div tags. Blank lines within HTML tags is a cue to Markdown to process the tags and the content within these tags as HTML.
+
-## Table of Contents
+ It is customary but not required to precede the _closing HTML_ tag with a blank tag as well.
-The table of contents (TOC) is automatically generated by fetching section titles and sub-section titles. By default the TOC is two levels deep, that is, it is limited to displaying 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 from the TOC.
+## Title
+
+Every guide document must have a title.
+
+The title should appear at the top of the physical page.
+Begin the title with the markdown `#` character. Alternatively, you can write the equivalent ``.
+
+```html
+ # Authors Style Guide
+```
+
+**Only one title (``) per document!**
+
+Title text should be in "Title Case", which means that you use capital letters to start the first works and all _principal_. Use lower case letters for _secondary words such as "in", "of", and "the".
+
+```html
+ # The Meat of the Matter
+```
+
+**Always follow the title with at least one blank line.**
+
+## Sections
+
+A typical document is divided into sections.
+
+All section heading text should be in "Sentence Case", which means the first word is capitalized and all other words are lower case.
+
+**Always follow the section heading with at least one blank line.**
+
+
+Main section heading
+
+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. Alternatively, you can write the equivalent `` 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
+
+
+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. Alternatively, you can write the equivalent `` HTML tag.
+
+The secondary heading should be followed by a blank line and then the content for that heading.
+
+```html
+ ### Secondary section heading
+
+ A secondary section ...
+```
+
+#### Additional section headings
+
+Try to minimize the heading depth, preferably only two. But more headings, such as this one, are permitted if they make sense.
+
+**N.B.**: The [Table-of-contents](#table-of-contents) generator only considers main (``) and secondary (``) headings.
+
+```html
+ #### Additional section headings
+
+ Try to minimize ...
+```
+
+## Subsections
+
+Subsections typically present extra detail and references to other pages.
+
+Use subsections for commentary that _enriches_ the reader's understanding of the text that precedes it.
+
+A subsection _must not_ contain anything _essential_ to that understanding. Don't put a critical instruction or a tutorial step in a subsection.
+
+A subsection is content within a `` 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.
-### Example
```html
-
-Heading not displated in the TOC
-
+This heading is not displayed in the TOC
```
-## 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. The sub-chapter titles should be displayed in the navigation panel, indented below the title of the main chapter.
-
-## Code Examples
-
-Code examples can be used to display code on a page. This code can be displayed inline or displaying by extracting from files. Code examples allow you to display code with line numbers, code of various programming languages, display these in tabbed interfaces and such.
-
-### Code-Example Attributes
-
-* path: a file in the content/examples folder
-* title: seen in the header of the code listing
-* region: name of a docregion, a merked region in a source file and explained in a section later in this guide
-* 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 specify that the starting line is 4. When not specified, line numbers are automatically displayed when there are 10 or more lines of code
-* 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.
-
-
- localhost:3000/hero/15
- localhost:3004/hero/again
-
-```html
-
- localhost:3000/hero/15
- localhost:3004/hero/again
-
-```
-
-#### Code from an External File
-
-Code-example 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). The code will be displayed as shown here.
-
-` tag and the `no-toc` class.
```html
-
-
+
+A guide without a TOC
+
```
+## Navigation
-#### Commands in a Command Window
+The navigation links at the top, left, and bottom of the screen are generated from the JSON configuration file, `content/navigation.json`.
-To display commands in a command window, you can use the code-shell class supported by code-examples.
+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".
-
- npm start
-
+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.
-The code below uses the code-shell class to display the command terminal and code within the terminal.
+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
-
- npm start
-
+{
+ "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.
-#### Example of Code to be Avoided
-
-To present code that users should avoid, you can use a class called avoid.
-
-
- <hero-details nghost-pmm-5>
- <h2 ngcontent-pmm-5>Mister Fantastic</h2>
- <hero-team ngcontent-pmm-5 nghost-pmm-6>
- <h3 _ngcontent-pmm-6>Losing Team</h3>
- </hero-team>
- </hero-details>
-
-
-The code to create this display is below.
+Add an _item_ node for your guide page as a child of the appropriate _header_ node. It probably looks something like this one.
```html
-
- nghost-pmm-5>
- ngcontent-pmm-5>Mister Fantastic
- ngcontent-pmm-5 nghost-pmm-6>
- _ngcontent-pmm-6>Losing Team
-
-
-
+{
+ "url": "guide/architecture",
+ "title": "Architecture",
+ "tooltip": "The basic building blocks of Angular applications."
+}
```
+A navigation node has the following properties:
-#### Example of HTML code
+* `url`- the URL of the guide page (_item node only_).
-Backticked code blocks can be used to enclose HTML code without using escape characters.
+* `title`- the text displayed in the side nav.
-```html
-
- Mister Fantastic
-
- Losing Team
-
-
-```
-You can use the syntax below to enclose HTML within a backticked code block.
+* `tooltip` - text that appears when the reader hovers over the navigation link.
-
-```html
- <hero-details>
- <h2>Mister Fantastic</h2>
- <hero-team>
- <h3>Losing Team</h3>
- </hero-team>
- </hero-details>
-```
-
+* `children` - an array of child nodes (_header node only_).
-#### Marking up a Source File
+* `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.
-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.
-
+
-Docregions are not supported in JSON
+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.
-#### Example of a nested docregion:
-
-// #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
+
- <code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero">
-</code-example>
+The current guidelines allow for a three-level navigation structure with two header levels. Don't add a third header level.
-<code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters">
-</code-example>
+
+
+
+## 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
-Here is code for the above code-examples that use docregions.
-
-
-
-
-
-
-
-HTML files can also contain docregions:
```html
-
-...
-
-...
+
+ npm start
+
```
-as can CSS files:
+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 page.
+
+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`.
+
+` like this
+
+
+```html
+
+
+```
+
+
+
+
+{@a code-tabs}
+
+Code Tabs
Code tabs display code much like Code examples do. The added advantage is that they can display mutiple code samples within a tabbed interface. Each tab is displayed using Code-pane.
-### Code-tabs Attributes
+#### Code-tabs attributes
-* linenums: true, false, display line numbers in the code in all tabs when the number of code statements are 10 or more
+* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are are enabled only when code for a tab pane has 10 or more lines.
-### Code-pane Attributes
+#### Code-pane attributes
-* path: a file in the content/examples folder
-* title: seen in the header of a tab
-* linenums: true, false, display line numbers for the code in this tab when the number of code statements are 10 or more
+* `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 are enabled only when there are 10 or more lines.
-The example below uses the source code for a small application that bundles with Webpack techniques. This will create multiple tabs, each with its own title and be 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.
+The example below uses the source code for a small application that bundles with Webpack techniques. This creates multiple tabs, each with its own title and be 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.
-
+
-
+
-
+
-
+
-The code below will create multiple tabs, each with its own title and be appropriately color coded.
+The markup below creates multiple tab pane, each with its own title and syntax-colored content.
```html
-
-
+
+
-
+
-
+
-
+
```
+{@a source-code-markup}
-{@a section-LiveExamples}
-## Live Examples
+## Source code markup
-Here is how we do live examples. All examples here will point to other guides such as TOH-6 for convenience.
+You must add special code snippet markup to sample source code files before they can be displayed by `` and `` components.
-### Plain Live Example
+
-When a live example is included in a guide, it allows readers to run the example and download the code that the Author has placed in the content/examples folder for their respective guide. A plain live example looks like this: ` 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.
+
+` or `` as you did in an example above like this:
+
+```html
+
+// #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`.
+
+` to the page you generate links that run sample code in the Plunker live coding environment and download that code to the reader's file system.
+
+Live examples (AKA "plunkers") are defined by one or more `plnkr.json` files in the root of a code sample folder. Each sample folder usually has a single unnamed definition file, the default `plnkr.json`.
+
+
+
+You can create additional, named definition files in the form `name.plnkr.json`. See `content/examples/testing` for examples.
+
+The schema for a `plnkr.json` hasn't been documented yet but looking at the `plnkr.json` files in the example folders should tell you most of what you need to know.
+
+
+
+Adding `Custom label and tooltip
-To replace 'live-example' with a title, you can provide a title as shown here.
+Give the live example anchor a custom label and tooltip by setting the `title` attribute.
+
+` tags:
-Another way to display aletrnative text for 'live-example' is to include it in the body of the live-example. The effect is the same as when you use the title attribute.
+Live example with content label
```html
-Live Example Flesh & Blood
+Live example with content label
```
-### Live Example from Another Guide
+Live example from another guide
-Example of live-example from the router guide Live Example from the Router guide .
+To link to a plunker 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 other than Default for Guide
+Live Example for named plunker
+
+To link to a plunker defined by a named `plnkr.json` file, set the `plnkr` attribute. The following example links to the plunker defined by `second.plnkr.json` in the current guide's directory.
+
+Live Example without download
+
+To skip the download link, add the `noDownload` attribute
+
+Just the plunker
+
```html
-Just the plunker
```
-### Live Example with only Download
+Live Example with download-only
+
+To skip the live plunker link and only link to the download, add the `downloadOnly` attribute.
+
+Download only
+
```html
-Download only
```
-### Live Example with Embedded Plunkers
-Embedded Plunkrs have default image. img allows you to override the default image.
+
+
+By default, a live example link opens a plunker in a separate browser tab.
+You can embed the plunker within the guide page itself by adding the `embedded` attribute.
+
+For performance reasons, the plunker does not start right away. The reader sees an image instead. Clicking the image starts the sometimes-slow process of launching the embedded plunker within an iframe on the page.
+
+You usually replace the default plunker 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/plunker/unused/click-to-run.png`.
+
```html
-
- My location has been marked using {@ section-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`{@ name}` syntax like this.
+
+
+ {@a ugly-anchors}
+
+#### Ugly, long section header anchors
-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/dir-of-page with the relative path to the page that has the location that the reader should reach.
+Now [link to that custom anchor name](#ugly-anchors) as you did before.
+
```html
-[alternative text] (path-to-page/dir-of-page/#section-Anchors)
+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
-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. Note that the content of an alert is indented to the right by two spaces.
-
-
+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 very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful alert.
+A helpful, informational alert.
-
-Here is sample code to generate alerts.
+Here is the markup for these alerts.
```html
- A very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful 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
-Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention to important occasions. Unlike alerts, callouts are designed to display multi-line content.
-
-
+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
-
-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
+**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
-
-A VERY IMPORTANT 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
+**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
-
-A VERY HELPFUL 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
+**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
-
-
-Here is sample code to generate important callouts.
+Here is the markup for the first of these callouts.
```html
-
+
+A critical point
-
-A VERY IMPORTANT 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
+**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
```
+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 be used to represent heirarchial data. Here is an example.
+Trees can represent hierarchical data.
@@ -509,7 +956,7 @@ Trees can be used to represent heirarchial data. Here is an example.
-Here is the code for this tree.
+Here is the markup for this file tree.
```html
@@ -552,7 +999,7 @@ Here is the code for this tree.
## Tables
-Tables can be used to present tabular data as it relates to each other.
+Use HTML tables to present tabular data.
-
-
-
- Framework
-
-
-
- Task
-
-
-
- Speed
-
-
-
-
+ Framework
+ Task
+ Speed
+
-
-
- AngularJS
-
-
-
- Routing
-
-
-
- Fast
-
-
-
-
+ AngularJSRouting
+ Fast
+
-
+ Angular v2Routing
+
- Angular 2
-
+ *Faster*
+
+
+
+
+ Angular v4Routing
- Routing
+
+ **Fastest :)**
+
-
-
- Faster
-
-
-
-
-
-
-
- Angular 4
-
-
-
- Routing
-
-
-
- Fastest :)
-
-
-
-
-
+
-Here is code for this table.
+Here is the markup for this table.
```html
-table
- tr
- th Framework
- th Task
- th Speed
- tr
- td AngularJS
- td Routing
- td fast
- tr
- td Angular 2
- td Routing
- td faster
+
+
+
+
+ Framework
+ Task
+ Speed
+
+
+ AngularJSRouting
+ Fast
+
+
+ Angular v2Routing
+
+
+
+ *Faster*
+
+
+
+
+ Angular v4Routing
+
+
+ **Fastest :)**
+
+
+
+
```
## Images
-### Using Images
+Image location
-HTML should be used to declare images in the docs. Do not use the markdown \!\[\.\.\.\]\(\.\.\.\) shorthand.
+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.
-The HTML to use is an <img src="..." alt="..."> 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 
is visible inline in the text.
+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"
```
-#### Floating Images
+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 `` tag, which styles the image within a drop-shadow frame. You'll need the editor's permission to skip the `` tag.
+
+Here's a conforming example
+
+
+ 
+
-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
-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:
+_Note that the HTML image element does not have a closing tag._
+
+Image dimensions
+
+The doc generator reads the image dimensions from the file and adds width and height attributes to the `img` tag automatically. If you want to control the size of the image, supply your own width and height attributes.
+
+Here's the "flying hero" at a more reasonable scale.
+
+
+
+
```html
+
+
+
+
+```
+
+Wide images can be a problem. Most browsers try to rescale the image but wide images may overflow the document in certain viewports.
+
+**Do not set a width greater than 700px**. If you wish to display a larger image, provide a link to the actual image that the user can click on to see the full size image separately as in this example of `source-map-explorer` output from the "Ahead-of-time Compilation" guide:
+
+
+
+ 
+
+
+
+Image compression
+
+Large image files can be slow to load, harming the user experience. Always compress the image.
+Consider using an image compression web site such as [tinypng](https://tinypng.com/ "tinypng").
+
+Floating images
+
+You can float the image to the left or right of text by applying the class="left" or class="right" attributes respectively.
+
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
+
+
+The markup for the above example is:
+
+```html
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
```
-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:
+Note that you generally don't wrap a floating image in a `` element.
+
+#### Floating within a subsection
+
+If you have a floating image inside an alert, callout, or a subsection, 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:
+
+
+
+
+
+ A subsection with **markdown** formatted text.
+
+
```html
-
- Some **markdown** formatted text.
+
+
+ A subsection with **markdown** formatted text.
-
-```
-
-#### 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.
-
- ![]()
-
-
-```
-
-
+```
\ No newline at end of file
diff --git a/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png
new file mode 100644
index 0000000000..22cd657e3e
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png differ
diff --git a/aio/content/images/guide/docs-style-guide/flying-hero.png b/aio/content/images/guide/docs-style-guide/flying-hero.png
new file mode 100644
index 0000000000..d8e43ea29a
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/flying-hero.png differ
diff --git a/aio/content/navigation.json b/aio/content/navigation.json
index 1008f8f9e7..b4c75e37c6 100644
--- a/aio/content/navigation.json
+++ b/aio/content/navigation.json
@@ -54,6 +54,13 @@
"hidden": true
},
+ {
+ "url": "guide/docs-style-guide",
+ "title": "Doc authors style guide",
+ "tooltip": "Style guide for documentation authors",
+ "hidden": true
+ },
+
{
"url": "guide/quickstart",
"title": "Getting Started",
+Main section heading +
+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. Alternatively, you can write the equivalent `` 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
+
+
+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. Alternatively, you can write the equivalent `` HTML tag.
+
+The secondary heading should be followed by a blank line and then the content for that heading.
+
+```html
+ ### Secondary section heading
+
+ A secondary section ...
+```
+
+#### Additional section headings
+
+Try to minimize the heading depth, preferably only two. But more headings, such as this one, are permitted if they make sense.
+
+**N.B.**: The [Table-of-contents](#table-of-contents) generator only considers main (``) and secondary (``) headings.
+
+```html
+ #### Additional section headings
+
+ Try to minimize ...
+```
+
+## Subsections
+
+Subsections typically present extra detail and references to other pages.
+
+Use subsections for commentary that _enriches_ the reader's understanding of the text that precedes it.
+
+A subsection _must not_ contain anything _essential_ to that understanding. Don't put a critical instruction or a tutorial step in a subsection.
+
+A subsection is content within a `` 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.
-### Example
```html
-
-Heading not displated in the TOC
-
+This heading is not displayed in the TOC
```
-## 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. The sub-chapter titles should be displayed in the navigation panel, indented below the title of the main chapter.
-
-## Code Examples
-
-Code examples can be used to display code on a page. This code can be displayed inline or displaying by extracting from files. Code examples allow you to display code with line numbers, code of various programming languages, display these in tabbed interfaces and such.
-
-### Code-Example Attributes
-
-* path: a file in the content/examples folder
-* title: seen in the header of the code listing
-* region: name of a docregion, a merked region in a source file and explained in a section later in this guide
-* 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 specify that the starting line is 4. When not specified, line numbers are automatically displayed when there are 10 or more lines of code
-* 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.
-
-
- localhost:3000/hero/15
- localhost:3004/hero/again
-
-```html
-
- localhost:3000/hero/15
- localhost:3004/hero/again
-
-```
-
-#### Code from an External File
-
-Code-example 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). The code will be displayed as shown here.
-
-` tag and the `no-toc` class.
```html
-
-
+
+A guide without a TOC
+
```
+## Navigation
-#### Commands in a Command Window
+The navigation links at the top, left, and bottom of the screen are generated from the JSON configuration file, `content/navigation.json`.
-To display commands in a command window, you can use the code-shell class supported by code-examples.
+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".
-
- npm start
-
+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.
-The code below uses the code-shell class to display the command terminal and code within the terminal.
+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
-
- npm start
-
+{
+ "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.
-#### Example of Code to be Avoided
-
-To present code that users should avoid, you can use a class called avoid.
-
-
- <hero-details nghost-pmm-5>
- <h2 ngcontent-pmm-5>Mister Fantastic</h2>
- <hero-team ngcontent-pmm-5 nghost-pmm-6>
- <h3 _ngcontent-pmm-6>Losing Team</h3>
- </hero-team>
- </hero-details>
-
-
-The code to create this display is below.
+Add an _item_ node for your guide page as a child of the appropriate _header_ node. It probably looks something like this one.
```html
-
- nghost-pmm-5>
- ngcontent-pmm-5>Mister Fantastic
- ngcontent-pmm-5 nghost-pmm-6>
- _ngcontent-pmm-6>Losing Team
-
-
-
+{
+ "url": "guide/architecture",
+ "title": "Architecture",
+ "tooltip": "The basic building blocks of Angular applications."
+}
```
+A navigation node has the following properties:
-#### Example of HTML code
+* `url`- the URL of the guide page (_item node only_).
-Backticked code blocks can be used to enclose HTML code without using escape characters.
+* `title`- the text displayed in the side nav.
-```html
-
- Mister Fantastic
-
- Losing Team
-
-
-```
-You can use the syntax below to enclose HTML within a backticked code block.
+* `tooltip` - text that appears when the reader hovers over the navigation link.
-
-```html
- <hero-details>
- <h2>Mister Fantastic</h2>
- <hero-team>
- <h3>Losing Team</h3>
- </hero-team>
- </hero-details>
-```
-
+* `children` - an array of child nodes (_header node only_).
-#### Marking up a Source File
+* `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.
-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.
-
+
-Docregions are not supported in JSON
+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.
-#### Example of a nested docregion:
-
-// #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
+
- <code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero">
-</code-example>
+The current guidelines allow for a three-level navigation structure with two header levels. Don't add a third header level.
-<code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters">
-</code-example>
+
+
+
+## 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
-Here is code for the above code-examples that use docregions.
-
-
-
-
-
-
-
-HTML files can also contain docregions:
```html
-
-...
-
-...
+
+ npm start
+
```
-as can CSS files:
+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 page.
+
+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`.
+
+` like this
+
+
+```html
+
+
+```
+
+
+
+
+{@a code-tabs}
+
+Code Tabs
Code tabs display code much like Code examples do. The added advantage is that they can display mutiple code samples within a tabbed interface. Each tab is displayed using Code-pane.
-### Code-tabs Attributes
+#### Code-tabs attributes
-* linenums: true, false, display line numbers in the code in all tabs when the number of code statements are 10 or more
+* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are are enabled only when code for a tab pane has 10 or more lines.
-### Code-pane Attributes
+#### Code-pane attributes
-* path: a file in the content/examples folder
-* title: seen in the header of a tab
-* linenums: true, false, display line numbers for the code in this tab when the number of code statements are 10 or more
+* `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 are enabled only when there are 10 or more lines.
-The example below uses the source code for a small application that bundles with Webpack techniques. This will create multiple tabs, each with its own title and be 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.
+The example below uses the source code for a small application that bundles with Webpack techniques. This creates multiple tabs, each with its own title and be 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.
-
+
-
+
-
+
-
+
-The code below will create multiple tabs, each with its own title and be appropriately color coded.
+The markup below creates multiple tab pane, each with its own title and syntax-colored content.
```html
-
-
+
+
-
+
-
+
-
+
```
+{@a source-code-markup}
-{@a section-LiveExamples}
-## Live Examples
+## Source code markup
-Here is how we do live examples. All examples here will point to other guides such as TOH-6 for convenience.
+You must add special code snippet markup to sample source code files before they can be displayed by `` and `` components.
-### Plain Live Example
+
-When a live example is included in a guide, it allows readers to run the example and download the code that the Author has placed in the content/examples folder for their respective guide. A plain live example looks like this: ` 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.
+
+` or `` as you did in an example above like this:
+
+```html
+
+// #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`.
+
+` to the page you generate links that run sample code in the Plunker live coding environment and download that code to the reader's file system.
+
+Live examples (AKA "plunkers") are defined by one or more `plnkr.json` files in the root of a code sample folder. Each sample folder usually has a single unnamed definition file, the default `plnkr.json`.
+
+
+
+You can create additional, named definition files in the form `name.plnkr.json`. See `content/examples/testing` for examples.
+
+The schema for a `plnkr.json` hasn't been documented yet but looking at the `plnkr.json` files in the example folders should tell you most of what you need to know.
+
+
+
+Adding `Custom label and tooltip
-To replace 'live-example' with a title, you can provide a title as shown here.
+Give the live example anchor a custom label and tooltip by setting the `title` attribute.
+
+` tags:
-Another way to display aletrnative text for 'live-example' is to include it in the body of the live-example. The effect is the same as when you use the title attribute.
+Live example with content label
```html
-Live Example Flesh & Blood
+Live example with content label
```
-### Live Example from Another Guide
+Live example from another guide
-Example of live-example from the router guide Live Example from the Router guide .
+To link to a plunker 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 other than Default for Guide
+Live Example for named plunker
+
+To link to a plunker defined by a named `plnkr.json` file, set the `plnkr` attribute. The following example links to the plunker defined by `second.plnkr.json` in the current guide's directory.
+
+Live Example without download
+
+To skip the download link, add the `noDownload` attribute
+
+Just the plunker
+
```html
-Just the plunker
```
-### Live Example with only Download
+Live Example with download-only
+
+To skip the live plunker link and only link to the download, add the `downloadOnly` attribute.
+
+Download only
+
```html
-Download only
```
-### Live Example with Embedded Plunkers
-Embedded Plunkrs have default image. img allows you to override the default image.
+
+
+By default, a live example link opens a plunker in a separate browser tab.
+You can embed the plunker within the guide page itself by adding the `embedded` attribute.
+
+For performance reasons, the plunker does not start right away. The reader sees an image instead. Clicking the image starts the sometimes-slow process of launching the embedded plunker within an iframe on the page.
+
+You usually replace the default plunker 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/plunker/unused/click-to-run.png`.
+
```html
-
- My location has been marked using {@ section-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`{@ name}` syntax like this.
+
+
+ {@a ugly-anchors}
+
+#### Ugly, long section header anchors
-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/dir-of-page with the relative path to the page that has the location that the reader should reach.
+Now [link to that custom anchor name](#ugly-anchors) as you did before.
+
```html
-[alternative text] (path-to-page/dir-of-page/#section-Anchors)
+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
-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. Note that the content of an alert is indented to the right by two spaces.
-
-
+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 very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful alert.
+A helpful, informational alert.
-
-Here is sample code to generate alerts.
+Here is the markup for these alerts.
```html
- A very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful 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
-Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention to important occasions. Unlike alerts, callouts are designed to display multi-line content.
-
-
+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
-
-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
+**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
-
-A VERY IMPORTANT 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
+**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
-
-A VERY HELPFUL 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
+**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
-
-
-Here is sample code to generate important callouts.
+Here is the markup for the first of these callouts.
```html
-
+
+A critical point
-
-A VERY IMPORTANT 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
+**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
```
+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 be used to represent heirarchial data. Here is an example.
+Trees can represent hierarchical data.
@@ -509,7 +956,7 @@ Trees can be used to represent heirarchial data. Here is an example.
-Here is the code for this tree.
+Here is the markup for this file tree.
```html
@@ -552,7 +999,7 @@ Here is the code for this tree.
## Tables
-Tables can be used to present tabular data as it relates to each other.
+Use HTML tables to present tabular data.
-
-
-
- Framework
-
-
-
- Task
-
-
-
- Speed
-
-
-
-
+ Framework
+ Task
+ Speed
+
-
-
- AngularJS
-
-
-
- Routing
-
-
-
- Fast
-
-
-
-
+ AngularJSRouting
+ Fast
+
-
+ Angular v2Routing
+
- Angular 2
-
+ *Faster*
+
+
+
+
+ Angular v4Routing
- Routing
+
+ **Fastest :)**
+
-
-
- Faster
-
-
-
-
-
-
-
- Angular 4
-
-
-
- Routing
-
-
-
- Fastest :)
-
-
-
-
-
+
-Here is code for this table.
+Here is the markup for this table.
```html
-table
- tr
- th Framework
- th Task
- th Speed
- tr
- td AngularJS
- td Routing
- td fast
- tr
- td Angular 2
- td Routing
- td faster
+
+
+
+
+ Framework
+ Task
+ Speed
+
+
+ AngularJSRouting
+ Fast
+
+
+ Angular v2Routing
+
+
+
+ *Faster*
+
+
+
+
+ Angular v4Routing
+
+
+ **Fastest :)**
+
+
+
+
```
## Images
-### Using Images
+Image location
-HTML should be used to declare images in the docs. Do not use the markdown \!\[\.\.\.\]\(\.\.\.\) shorthand.
+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.
-The HTML to use is an <img src="..." alt="..."> 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 is visible inline in the text.
+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"
```
-#### Floating Images
+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 `` tag, which styles the image within a drop-shadow frame. You'll need the editor's permission to skip the `` tag.
+
+Here's a conforming example
+
+
+
+
-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
-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:
+_Note that the HTML image element does not have a closing tag._
+
+Image dimensions
+
+The doc generator reads the image dimensions from the file and adds width and height attributes to the `img` tag automatically. If you want to control the size of the image, supply your own width and height attributes.
+
+Here's the "flying hero" at a more reasonable scale.
+
+
+
+
```html
+
+
+
+
+```
+
+Wide images can be a problem. Most browsers try to rescale the image but wide images may overflow the document in certain viewports.
+
+**Do not set a width greater than 700px**. If you wish to display a larger image, provide a link to the actual image that the user can click on to see the full size image separately as in this example of `source-map-explorer` output from the "Ahead-of-time Compilation" guide:
+
+
+
+
+
+
+
+Image compression
+
+Large image files can be slow to load, harming the user experience. Always compress the image.
+Consider using an image compression web site such as [tinypng](https://tinypng.com/ "tinypng").
+
+Floating images
+
+You can float the image to the left or right of text by applying the class="left" or class="right" attributes respectively.
+
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
+
+
+The markup for the above example is:
+
+```html
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
```
-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:
+Note that you generally don't wrap a floating image in a `` element.
+
+#### Floating within a subsection
+
+If you have a floating image inside an alert, callout, or a subsection, 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:
+
+
+
+
+
+ A subsection with **markdown** formatted text.
+
+
```html
-
- Some **markdown** formatted text.
+
+
+ A subsection with **markdown** formatted text.
-
-```
-
-#### 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.
-
- ![]()
-
-
-```
-
-
+```
\ No newline at end of file
diff --git a/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png
new file mode 100644
index 0000000000..22cd657e3e
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png differ
diff --git a/aio/content/images/guide/docs-style-guide/flying-hero.png b/aio/content/images/guide/docs-style-guide/flying-hero.png
new file mode 100644
index 0000000000..d8e43ea29a
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/flying-hero.png differ
diff --git a/aio/content/navigation.json b/aio/content/navigation.json
index 1008f8f9e7..b4c75e37c6 100644
--- a/aio/content/navigation.json
+++ b/aio/content/navigation.json
@@ -54,6 +54,13 @@
"hidden": true
},
+ {
+ "url": "guide/docs-style-guide",
+ "title": "Doc authors style guide",
+ "tooltip": "Style guide for documentation authors",
+ "hidden": true
+ },
+
{
"url": "guide/quickstart",
"title": "Getting Started",
`) and secondary (``) headings.
+
+```html
+ #### Additional section headings
+
+ Try to minimize ...
+```
+
+## Subsections
+
+Subsections typically present extra detail and references to other pages.
+
+Use subsections for commentary that _enriches_ the reader's understanding of the text that precedes it.
+
+A subsection _must not_ contain anything _essential_ to that understanding. Don't put a critical instruction or a tutorial step in a subsection.
+
+A subsection is content within a `` 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.
-### Example
```html
-
-Heading not displated in the TOC
-
+This heading is not displayed in the TOC
```
-## 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. The sub-chapter titles should be displayed in the navigation panel, indented below the title of the main chapter.
-
-## Code Examples
-
-Code examples can be used to display code on a page. This code can be displayed inline or displaying by extracting from files. Code examples allow you to display code with line numbers, code of various programming languages, display these in tabbed interfaces and such.
-
-### Code-Example Attributes
-
-* path: a file in the content/examples folder
-* title: seen in the header of the code listing
-* region: name of a docregion, a merked region in a source file and explained in a section later in this guide
-* 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 specify that the starting line is 4. When not specified, line numbers are automatically displayed when there are 10 or more lines of code
-* 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.
-
-
- localhost:3000/hero/15
- localhost:3004/hero/again
-
-```html
-
- localhost:3000/hero/15
- localhost:3004/hero/again
-
-```
-
-#### Code from an External File
-
-Code-example 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). The code will be displayed as shown here.
-
-` tag and the `no-toc` class.
```html
-
-
+
+A guide without a TOC
+
```
+## Navigation
-#### Commands in a Command Window
+The navigation links at the top, left, and bottom of the screen are generated from the JSON configuration file, `content/navigation.json`.
-To display commands in a command window, you can use the code-shell class supported by code-examples.
+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".
-
- npm start
-
+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.
-The code below uses the code-shell class to display the command terminal and code within the terminal.
+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
-
- npm start
-
+{
+ "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.
-#### Example of Code to be Avoided
-
-To present code that users should avoid, you can use a class called avoid.
-
-
- <hero-details nghost-pmm-5>
- <h2 ngcontent-pmm-5>Mister Fantastic</h2>
- <hero-team ngcontent-pmm-5 nghost-pmm-6>
- <h3 _ngcontent-pmm-6>Losing Team</h3>
- </hero-team>
- </hero-details>
-
-
-The code to create this display is below.
+Add an _item_ node for your guide page as a child of the appropriate _header_ node. It probably looks something like this one.
```html
-
- nghost-pmm-5>
- ngcontent-pmm-5>Mister Fantastic
- ngcontent-pmm-5 nghost-pmm-6>
- _ngcontent-pmm-6>Losing Team
-
-
-
+{
+ "url": "guide/architecture",
+ "title": "Architecture",
+ "tooltip": "The basic building blocks of Angular applications."
+}
```
+A navigation node has the following properties:
-#### Example of HTML code
+* `url`- the URL of the guide page (_item node only_).
-Backticked code blocks can be used to enclose HTML code without using escape characters.
+* `title`- the text displayed in the side nav.
-```html
-
- Mister Fantastic
-
- Losing Team
-
-
-```
-You can use the syntax below to enclose HTML within a backticked code block.
+* `tooltip` - text that appears when the reader hovers over the navigation link.
-
-```html
- <hero-details>
- <h2>Mister Fantastic</h2>
- <hero-team>
- <h3>Losing Team</h3>
- </hero-team>
- </hero-details>
-```
-
+* `children` - an array of child nodes (_header node only_).
-#### Marking up a Source File
+* `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.
-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.
-
+
-Docregions are not supported in JSON
+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.
-#### Example of a nested docregion:
-
-// #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
+
- <code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero">
-</code-example>
+The current guidelines allow for a three-level navigation structure with two header levels. Don't add a third header level.
-<code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters">
-</code-example>
+
+
+
+## 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
-Here is code for the above code-examples that use docregions.
-
-
-
-
-
-
-
-HTML files can also contain docregions:
```html
-
-...
-
-...
+
+ npm start
+
```
-as can CSS files:
+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 page.
+
+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`.
+
+` like this
+
+
+```html
+
+
+```
+
+
+
+
+{@a code-tabs}
+
+Code Tabs
Code tabs display code much like Code examples do. The added advantage is that they can display mutiple code samples within a tabbed interface. Each tab is displayed using Code-pane.
-### Code-tabs Attributes
+#### Code-tabs attributes
-* linenums: true, false, display line numbers in the code in all tabs when the number of code statements are 10 or more
+* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are are enabled only when code for a tab pane has 10 or more lines.
-### Code-pane Attributes
+#### Code-pane attributes
-* path: a file in the content/examples folder
-* title: seen in the header of a tab
-* linenums: true, false, display line numbers for the code in this tab when the number of code statements are 10 or more
+* `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 are enabled only when there are 10 or more lines.
-The example below uses the source code for a small application that bundles with Webpack techniques. This will create multiple tabs, each with its own title and be 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.
+The example below uses the source code for a small application that bundles with Webpack techniques. This creates multiple tabs, each with its own title and be 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.
-
+
-
+
-
+
-
+
-The code below will create multiple tabs, each with its own title and be appropriately color coded.
+The markup below creates multiple tab pane, each with its own title and syntax-colored content.
```html
-
-
+
+
-
+
-
+
-
+
```
+{@a source-code-markup}
-{@a section-LiveExamples}
-## Live Examples
+## Source code markup
-Here is how we do live examples. All examples here will point to other guides such as TOH-6 for convenience.
+You must add special code snippet markup to sample source code files before they can be displayed by `` and `` components.
-### Plain Live Example
+
-When a live example is included in a guide, it allows readers to run the example and download the code that the Author has placed in the content/examples folder for their respective guide. A plain live example looks like this: ` 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.
+
+` or `` as you did in an example above like this:
+
+```html
+
+// #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`.
+
+` to the page you generate links that run sample code in the Plunker live coding environment and download that code to the reader's file system.
+
+Live examples (AKA "plunkers") are defined by one or more `plnkr.json` files in the root of a code sample folder. Each sample folder usually has a single unnamed definition file, the default `plnkr.json`.
+
+
+
+You can create additional, named definition files in the form `name.plnkr.json`. See `content/examples/testing` for examples.
+
+The schema for a `plnkr.json` hasn't been documented yet but looking at the `plnkr.json` files in the example folders should tell you most of what you need to know.
+
+
+
+Adding `Custom label and tooltip
-To replace 'live-example' with a title, you can provide a title as shown here.
+Give the live example anchor a custom label and tooltip by setting the `title` attribute.
+
+` tags:
-Another way to display aletrnative text for 'live-example' is to include it in the body of the live-example. The effect is the same as when you use the title attribute.
+Live example with content label
```html
-Live Example Flesh & Blood
+Live example with content label
```
-### Live Example from Another Guide
+Live example from another guide
-Example of live-example from the router guide Live Example from the Router guide .
+To link to a plunker 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 other than Default for Guide
+Live Example for named plunker
+
+To link to a plunker defined by a named `plnkr.json` file, set the `plnkr` attribute. The following example links to the plunker defined by `second.plnkr.json` in the current guide's directory.
+
+Live Example without download
+
+To skip the download link, add the `noDownload` attribute
+
+Just the plunker
+
```html
-Just the plunker
```
-### Live Example with only Download
+Live Example with download-only
+
+To skip the live plunker link and only link to the download, add the `downloadOnly` attribute.
+
+Download only
+
```html
-Download only
```
-### Live Example with Embedded Plunkers
-Embedded Plunkrs have default image. img allows you to override the default image.
+
+
+By default, a live example link opens a plunker in a separate browser tab.
+You can embed the plunker within the guide page itself by adding the `embedded` attribute.
+
+For performance reasons, the plunker does not start right away. The reader sees an image instead. Clicking the image starts the sometimes-slow process of launching the embedded plunker within an iframe on the page.
+
+You usually replace the default plunker 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/plunker/unused/click-to-run.png`.
+
```html
-
- My location has been marked using {@ section-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`{@ name}` syntax like this.
+
+
+ {@a ugly-anchors}
+
+#### Ugly, long section header anchors
-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/dir-of-page with the relative path to the page that has the location that the reader should reach.
+Now [link to that custom anchor name](#ugly-anchors) as you did before.
+
```html
-[alternative text] (path-to-page/dir-of-page/#section-Anchors)
+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
-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. Note that the content of an alert is indented to the right by two spaces.
-
-
+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 very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful alert.
+A helpful, informational alert.
-
-Here is sample code to generate alerts.
+Here is the markup for these alerts.
```html
- A very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful 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
-Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention to important occasions. Unlike alerts, callouts are designed to display multi-line content.
-
-
+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
-
-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
+**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
-
-A VERY IMPORTANT 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
+**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
-
-A VERY HELPFUL 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
+**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
-
-
-Here is sample code to generate important callouts.
+Here is the markup for the first of these callouts.
```html
-
+
+A critical point
-
-A VERY IMPORTANT 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
+**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
```
+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 be used to represent heirarchial data. Here is an example.
+Trees can represent hierarchical data.
@@ -509,7 +956,7 @@ Trees can be used to represent heirarchial data. Here is an example.
-Here is the code for this tree.
+Here is the markup for this file tree.
```html
@@ -552,7 +999,7 @@ Here is the code for this tree.
## Tables
-Tables can be used to present tabular data as it relates to each other.
+Use HTML tables to present tabular data.
-
-
-
- Framework
-
-
-
- Task
-
-
-
- Speed
-
-
-
-
+ Framework
+ Task
+ Speed
+
-
-
- AngularJS
-
-
-
- Routing
-
-
-
- Fast
-
-
-
-
+ AngularJSRouting
+ Fast
+
-
+ Angular v2Routing
+
- Angular 2
-
+ *Faster*
+
+
+
+
+ Angular v4Routing
- Routing
+
+ **Fastest :)**
+
-
-
- Faster
-
-
-
-
-
-
-
- Angular 4
-
-
-
- Routing
-
-
-
- Fastest :)
-
-
-
-
-
+
-Here is code for this table.
+Here is the markup for this table.
```html
-table
- tr
- th Framework
- th Task
- th Speed
- tr
- td AngularJS
- td Routing
- td fast
- tr
- td Angular 2
- td Routing
- td faster
+
+
+
+
+ Framework
+ Task
+ Speed
+
+
+ AngularJSRouting
+ Fast
+
+
+ Angular v2Routing
+
+
+
+ *Faster*
+
+
+
+
+ Angular v4Routing
+
+
+ **Fastest :)**
+
+
+
+
```
## Images
-### Using Images
+Image location
-HTML should be used to declare images in the docs. Do not use the markdown \!\[\.\.\.\]\(\.\.\.\) shorthand.
+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.
-The HTML to use is an <img src="..." alt="..."> 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 is visible inline in the text.
+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"
```
-#### Floating Images
+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 `` tag, which styles the image within a drop-shadow frame. You'll need the editor's permission to skip the `` tag.
+
+Here's a conforming example
+
+
+
+
-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
-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:
+_Note that the HTML image element does not have a closing tag._
+
+Image dimensions
+
+The doc generator reads the image dimensions from the file and adds width and height attributes to the `img` tag automatically. If you want to control the size of the image, supply your own width and height attributes.
+
+Here's the "flying hero" at a more reasonable scale.
+
+
+
+
```html
+
+
+
+
+```
+
+Wide images can be a problem. Most browsers try to rescale the image but wide images may overflow the document in certain viewports.
+
+**Do not set a width greater than 700px**. If you wish to display a larger image, provide a link to the actual image that the user can click on to see the full size image separately as in this example of `source-map-explorer` output from the "Ahead-of-time Compilation" guide:
+
+
+
+
+
+
+
+Image compression
+
+Large image files can be slow to load, harming the user experience. Always compress the image.
+Consider using an image compression web site such as [tinypng](https://tinypng.com/ "tinypng").
+
+Floating images
+
+You can float the image to the left or right of text by applying the class="left" or class="right" attributes respectively.
+
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
+
+
+The markup for the above example is:
+
+```html
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
```
-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:
+Note that you generally don't wrap a floating image in a `` element.
+
+#### Floating within a subsection
+
+If you have a floating image inside an alert, callout, or a subsection, 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:
+
+
+
+
+
+ A subsection with **markdown** formatted text.
+
+
```html
-
- Some **markdown** formatted text.
+
+
+ A subsection with **markdown** formatted text.
-
-```
-
-#### 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.
-
- ![]()
-
-
-```
-
-
+```
\ No newline at end of file
diff --git a/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png
new file mode 100644
index 0000000000..22cd657e3e
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png differ
diff --git a/aio/content/images/guide/docs-style-guide/flying-hero.png b/aio/content/images/guide/docs-style-guide/flying-hero.png
new file mode 100644
index 0000000000..d8e43ea29a
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/flying-hero.png differ
diff --git a/aio/content/navigation.json b/aio/content/navigation.json
index 1008f8f9e7..b4c75e37c6 100644
--- a/aio/content/navigation.json
+++ b/aio/content/navigation.json
@@ -54,6 +54,13 @@
"hidden": true
},
+ {
+ "url": "guide/docs-style-guide",
+ "title": "Doc authors style guide",
+ "tooltip": "Style guide for documentation authors",
+ "hidden": true
+ },
+
{
"url": "guide/quickstart",
"title": "Getting Started",
` 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.
+
+` or `
+
+ 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.
-### Example
```html
-
-Heading not displated in the TOC
-
+This heading is not displayed in the TOC
```
-## 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. The sub-chapter titles should be displayed in the navigation panel, indented below the title of the main chapter.
-
-## Code Examples
-
-Code examples can be used to display code on a page. This code can be displayed inline or displaying by extracting from files. Code examples allow you to display code with line numbers, code of various programming languages, display these in tabbed interfaces and such.
-
-### Code-Example Attributes
-
-* path: a file in the content/examples folder
-* title: seen in the header of the code listing
-* region: name of a docregion, a merked region in a source file and explained in a section later in this guide
-* 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 specify that the starting line is 4. When not specified, line numbers are automatically displayed when there are 10 or more lines of code
-* 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.
-
-
- localhost:3000/hero/15
- localhost:3004/hero/again
-
-```html
-
- localhost:3000/hero/15
- localhost:3004/hero/again
-
-```
-
-#### Code from an External File
-
-Code-example 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). The code will be displayed as shown here.
-
-` tag and the `no-toc` class.
```html
-
-
+
+A guide without a TOC
+
```
+## Navigation
-#### Commands in a Command Window
+The navigation links at the top, left, and bottom of the screen are generated from the JSON configuration file, `content/navigation.json`.
-To display commands in a command window, you can use the code-shell class supported by code-examples.
+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".
-
- npm start
-
+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.
-The code below uses the code-shell class to display the command terminal and code within the terminal.
+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
-
- npm start
-
+{
+ "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.
-#### Example of Code to be Avoided
-
-To present code that users should avoid, you can use a class called avoid.
-
-
- <hero-details nghost-pmm-5>
- <h2 ngcontent-pmm-5>Mister Fantastic</h2>
- <hero-team ngcontent-pmm-5 nghost-pmm-6>
- <h3 _ngcontent-pmm-6>Losing Team</h3>
- </hero-team>
- </hero-details>
-
-
-The code to create this display is below.
+Add an _item_ node for your guide page as a child of the appropriate _header_ node. It probably looks something like this one.
```html
-
- nghost-pmm-5>
- ngcontent-pmm-5>Mister Fantastic
- ngcontent-pmm-5 nghost-pmm-6>
- _ngcontent-pmm-6>Losing Team
-
-
-
+{
+ "url": "guide/architecture",
+ "title": "Architecture",
+ "tooltip": "The basic building blocks of Angular applications."
+}
```
+A navigation node has the following properties:
-#### Example of HTML code
+* `url`- the URL of the guide page (_item node only_).
-Backticked code blocks can be used to enclose HTML code without using escape characters.
+* `title`- the text displayed in the side nav.
-```html
-
- Mister Fantastic
-
- Losing Team
-
-
-```
-You can use the syntax below to enclose HTML within a backticked code block.
+* `tooltip` - text that appears when the reader hovers over the navigation link.
-
-```html
- <hero-details>
- <h2>Mister Fantastic</h2>
- <hero-team>
- <h3>Losing Team</h3>
- </hero-team>
- </hero-details>
-```
-
+* `children` - an array of child nodes (_header node only_).
-#### Marking up a Source File
+* `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.
-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.
-
+
-Docregions are not supported in JSON
+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.
-#### Example of a nested docregion:
-
-// #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
+
- <code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero">
-</code-example>
+The current guidelines allow for a three-level navigation structure with two header levels. Don't add a third header level.
-<code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters">
-</code-example>
+
+
+
+## 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
-Here is code for the above code-examples that use docregions.
-
-
-
-
-
-
-
-HTML files can also contain docregions:
```html
-
-...
-
-...
+
+ npm start
+
```
-as can CSS files:
+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 page.
+
+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`.
+
+` like this
+
+
+```html
+
+
+```
+
+
+
+
+{@a code-tabs}
+
+Code Tabs
Code tabs display code much like Code examples do. The added advantage is that they can display mutiple code samples within a tabbed interface. Each tab is displayed using Code-pane.
-### Code-tabs Attributes
+#### Code-tabs attributes
-* linenums: true, false, display line numbers in the code in all tabs when the number of code statements are 10 or more
+* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are are enabled only when code for a tab pane has 10 or more lines.
-### Code-pane Attributes
+#### Code-pane attributes
-* path: a file in the content/examples folder
-* title: seen in the header of a tab
-* linenums: true, false, display line numbers for the code in this tab when the number of code statements are 10 or more
+* `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 are enabled only when there are 10 or more lines.
-The example below uses the source code for a small application that bundles with Webpack techniques. This will create multiple tabs, each with its own title and be 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.
+The example below uses the source code for a small application that bundles with Webpack techniques. This creates multiple tabs, each with its own title and be 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.
-
+
-
+
-
+
-
+
-The code below will create multiple tabs, each with its own title and be appropriately color coded.
+The markup below creates multiple tab pane, each with its own title and syntax-colored content.
```html
-
-
+
+
-
+
-
+
-
+
```
+{@a source-code-markup}
-{@a section-LiveExamples}
-## Live Examples
+## Source code markup
-Here is how we do live examples. All examples here will point to other guides such as TOH-6 for convenience.
+You must add special code snippet markup to sample source code files before they can be displayed by `` and `` components.
-### Plain Live Example
+
-When a live example is included in a guide, it allows readers to run the example and download the code that the Author has placed in the content/examples folder for their respective guide. A plain live example looks like this: ` 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.
+
+` or `` as you did in an example above like this:
+
+```html
+
+// #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`.
+
+` to the page you generate links that run sample code in the Plunker live coding environment and download that code to the reader's file system.
+
+Live examples (AKA "plunkers") are defined by one or more `plnkr.json` files in the root of a code sample folder. Each sample folder usually has a single unnamed definition file, the default `plnkr.json`.
+
+
+
+You can create additional, named definition files in the form `name.plnkr.json`. See `content/examples/testing` for examples.
+
+The schema for a `plnkr.json` hasn't been documented yet but looking at the `plnkr.json` files in the example folders should tell you most of what you need to know.
+
+
+
+Adding `Custom label and tooltip
-To replace 'live-example' with a title, you can provide a title as shown here.
+Give the live example anchor a custom label and tooltip by setting the `title` attribute.
+
+` tags:
-Another way to display aletrnative text for 'live-example' is to include it in the body of the live-example. The effect is the same as when you use the title attribute.
+Live example with content label
```html
-Live Example Flesh & Blood
+Live example with content label
```
-### Live Example from Another Guide
+Live example from another guide
-Example of live-example from the router guide Live Example from the Router guide .
+To link to a plunker 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 other than Default for Guide
+Live Example for named plunker
+
+To link to a plunker defined by a named `plnkr.json` file, set the `plnkr` attribute. The following example links to the plunker defined by `second.plnkr.json` in the current guide's directory.
+
+Live Example without download
+
+To skip the download link, add the `noDownload` attribute
+
+Just the plunker
+
```html
-Just the plunker
```
-### Live Example with only Download
+Live Example with download-only
+
+To skip the live plunker link and only link to the download, add the `downloadOnly` attribute.
+
+Download only
+
```html
-Download only
```
-### Live Example with Embedded Plunkers
-Embedded Plunkrs have default image. img allows you to override the default image.
+
+
+By default, a live example link opens a plunker in a separate browser tab.
+You can embed the plunker within the guide page itself by adding the `embedded` attribute.
+
+For performance reasons, the plunker does not start right away. The reader sees an image instead. Clicking the image starts the sometimes-slow process of launching the embedded plunker within an iframe on the page.
+
+You usually replace the default plunker 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/plunker/unused/click-to-run.png`.
+
```html
-
- My location has been marked using {@ section-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`{@ name}` syntax like this.
+
+
+ {@a ugly-anchors}
+
+#### Ugly, long section header anchors
-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/dir-of-page with the relative path to the page that has the location that the reader should reach.
+Now [link to that custom anchor name](#ugly-anchors) as you did before.
+
```html
-[alternative text] (path-to-page/dir-of-page/#section-Anchors)
+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
-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. Note that the content of an alert is indented to the right by two spaces.
-
-
+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 very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful alert.
+A helpful, informational alert.
-
-Here is sample code to generate alerts.
+Here is the markup for these alerts.
```html
- A very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful 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
-Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention to important occasions. Unlike alerts, callouts are designed to display multi-line content.
-
-
+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
-
-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
+**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
-
-A VERY IMPORTANT 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
+**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
-
-A VERY HELPFUL 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
+**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
-
-
-Here is sample code to generate important callouts.
+Here is the markup for the first of these callouts.
```html
-
+
+A critical point
-
-A VERY IMPORTANT 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
+**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
```
+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 be used to represent heirarchial data. Here is an example.
+Trees can represent hierarchical data.
@@ -509,7 +956,7 @@ Trees can be used to represent heirarchial data. Here is an example.
-Here is the code for this tree.
+Here is the markup for this file tree.
```html
@@ -552,7 +999,7 @@ Here is the code for this tree.
## Tables
-Tables can be used to present tabular data as it relates to each other.
+Use HTML tables to present tabular data.
-
-
-
- Framework
-
-
-
- Task
-
-
-
- Speed
-
-
-
-
+ Framework
+ Task
+ Speed
+
-
-
- AngularJS
-
-
-
- Routing
-
-
-
- Fast
-
-
-
-
+ AngularJSRouting
+ Fast
+
-
+ Angular v2Routing
+
- Angular 2
-
+ *Faster*
+
+
+
+
+ Angular v4Routing
- Routing
+
+ **Fastest :)**
+
-
-
- Faster
-
-
-
-
-
-
-
- Angular 4
-
-
-
- Routing
-
-
-
- Fastest :)
-
-
-
-
-
+
-Here is code for this table.
+Here is the markup for this table.
```html
-table
- tr
- th Framework
- th Task
- th Speed
- tr
- td AngularJS
- td Routing
- td fast
- tr
- td Angular 2
- td Routing
- td faster
+
+
+
+
+ Framework
+ Task
+ Speed
+
+
+ AngularJSRouting
+ Fast
+
+
+ Angular v2Routing
+
+
+
+ *Faster*
+
+
+
+
+ Angular v4Routing
+
+
+ **Fastest :)**
+
+
+
+
```
## Images
-### Using Images
+Image location
-HTML should be used to declare images in the docs. Do not use the markdown \!\[\.\.\.\]\(\.\.\.\) shorthand.
+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.
-The HTML to use is an <img src="..." alt="..."> 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 is visible inline in the text.
+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"
```
-#### Floating Images
+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 `` tag, which styles the image within a drop-shadow frame. You'll need the editor's permission to skip the `` tag.
+
+Here's a conforming example
+
+
+
+
-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
-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:
+_Note that the HTML image element does not have a closing tag._
+
+Image dimensions
+
+The doc generator reads the image dimensions from the file and adds width and height attributes to the `img` tag automatically. If you want to control the size of the image, supply your own width and height attributes.
+
+Here's the "flying hero" at a more reasonable scale.
+
+
+
+
```html
+
+
+
+
+```
+
+Wide images can be a problem. Most browsers try to rescale the image but wide images may overflow the document in certain viewports.
+
+**Do not set a width greater than 700px**. If you wish to display a larger image, provide a link to the actual image that the user can click on to see the full size image separately as in this example of `source-map-explorer` output from the "Ahead-of-time Compilation" guide:
+
+
+
+
+
+
+
+Image compression
+
+Large image files can be slow to load, harming the user experience. Always compress the image.
+Consider using an image compression web site such as [tinypng](https://tinypng.com/ "tinypng").
+
+Floating images
+
+You can float the image to the left or right of text by applying the class="left" or class="right" attributes respectively.
+
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
+
+
+The markup for the above example is:
+
+```html
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
```
-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:
+Note that you generally don't wrap a floating image in a `` element.
+
+#### Floating within a subsection
+
+If you have a floating image inside an alert, callout, or a subsection, 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:
+
+
+
+
+
+ A subsection with **markdown** formatted text.
+
+
```html
-
- Some **markdown** formatted text.
+
+
+ A subsection with **markdown** formatted text.
-
-```
-
-#### 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.
-
- ![]()
-
-
-```
-
-
+```
\ No newline at end of file
diff --git a/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png
new file mode 100644
index 0000000000..22cd657e3e
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png differ
diff --git a/aio/content/images/guide/docs-style-guide/flying-hero.png b/aio/content/images/guide/docs-style-guide/flying-hero.png
new file mode 100644
index 0000000000..d8e43ea29a
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/flying-hero.png differ
diff --git a/aio/content/navigation.json b/aio/content/navigation.json
index 1008f8f9e7..b4c75e37c6 100644
--- a/aio/content/navigation.json
+++ b/aio/content/navigation.json
@@ -54,6 +54,13 @@
"hidden": true
},
+ {
+ "url": "guide/docs-style-guide",
+ "title": "Doc authors style guide",
+ "tooltip": "Style guide for documentation authors",
+ "hidden": true
+ },
+
{
"url": "guide/quickstart",
"title": "Getting Started",
- -Heading not displated in the TOC - +This heading is not displayed in the TOC
``` -## 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. The sub-chapter titles should be displayed in the navigation panel, indented below the title of the main chapter. - -## Code Examples - -Code examples can be used to display code on a page. This code can be displayed inline or displaying by extracting from files. Code examples allow you to display code with line numbers, code of various programming languages, display these in tabbed interfaces and such. - -### Code-Example Attributes - -* path: a file in the content/examples folder -* title: seen in the header of the code listing -* region: name of a docregion, a merked region in a source file and explained in a section later in this guide -* 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 specify that the starting line is 4. When not specified, line numbers are automatically displayed when there are 10 or more lines of code -* 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. - -` tag and the `no-toc` class.
```html
-
-
+
+A guide without a TOC
+
```
+## Navigation
-#### Commands in a Command Window
+The navigation links at the top, left, and bottom of the screen are generated from the JSON configuration file, `content/navigation.json`.
-To display commands in a command window, you can use the code-shell class supported by code-examples.
+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".
-
- npm start
-
+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.
-The code below uses the code-shell class to display the command terminal and code within the terminal.
+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
-
- npm start
-
+{
+ "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.
-#### Example of Code to be Avoided
-
-To present code that users should avoid, you can use a class called avoid.
-
-
- <hero-details nghost-pmm-5>
- <h2 ngcontent-pmm-5>Mister Fantastic</h2>
- <hero-team ngcontent-pmm-5 nghost-pmm-6>
- <h3 _ngcontent-pmm-6>Losing Team</h3>
- </hero-team>
- </hero-details>
-
-
-The code to create this display is below.
+Add an _item_ node for your guide page as a child of the appropriate _header_ node. It probably looks something like this one.
```html
-
- nghost-pmm-5>
- ngcontent-pmm-5>Mister Fantastic
- ngcontent-pmm-5 nghost-pmm-6>
- _ngcontent-pmm-6>Losing Team
-
-
-
+{
+ "url": "guide/architecture",
+ "title": "Architecture",
+ "tooltip": "The basic building blocks of Angular applications."
+}
```
+A navigation node has the following properties:
-#### Example of HTML code
+* `url`- the URL of the guide page (_item node only_).
-Backticked code blocks can be used to enclose HTML code without using escape characters.
+* `title`- the text displayed in the side nav.
-```html
-
- Mister Fantastic
-
- Losing Team
-
-
-```
-You can use the syntax below to enclose HTML within a backticked code block.
+* `tooltip` - text that appears when the reader hovers over the navigation link.
-
-```html
- <hero-details>
- <h2>Mister Fantastic</h2>
- <hero-team>
- <h3>Losing Team</h3>
- </hero-team>
- </hero-details>
-```
-
+* `children` - an array of child nodes (_header node only_).
-#### Marking up a Source File
+* `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.
-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.
-
+
-Docregions are not supported in JSON
+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.
-#### Example of a nested docregion:
-
-// #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
+
- <code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero">
-</code-example>
+The current guidelines allow for a three-level navigation structure with two header levels. Don't add a third header level.
-<code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters">
-</code-example>
+
+
+
+## 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
-Here is code for the above code-examples that use docregions.
-
-
-
-
-
-
-
-HTML files can also contain docregions:
```html
-
-...
-
-...
+
+ npm start
+
```
-as can CSS files:
+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 page.
+
+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`.
+
+` like this
+
+
+```html
+
+
+```
+
+
+
+
+{@a code-tabs}
+
+Code Tabs
Code tabs display code much like Code examples do. The added advantage is that they can display mutiple code samples within a tabbed interface. Each tab is displayed using Code-pane.
-### Code-tabs Attributes
+#### Code-tabs attributes
-* linenums: true, false, display line numbers in the code in all tabs when the number of code statements are 10 or more
+* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are are enabled only when code for a tab pane has 10 or more lines.
-### Code-pane Attributes
+#### Code-pane attributes
-* path: a file in the content/examples folder
-* title: seen in the header of a tab
-* linenums: true, false, display line numbers for the code in this tab when the number of code statements are 10 or more
+* `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 are enabled only when there are 10 or more lines.
-The example below uses the source code for a small application that bundles with Webpack techniques. This will create multiple tabs, each with its own title and be 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.
+The example below uses the source code for a small application that bundles with Webpack techniques. This creates multiple tabs, each with its own title and be 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.
-
+
-
+
-
+
-
+
-The code below will create multiple tabs, each with its own title and be appropriately color coded.
+The markup below creates multiple tab pane, each with its own title and syntax-colored content.
```html
-
-
+
+
-
+
-
+
-
+
```
+{@a source-code-markup}
-{@a section-LiveExamples}
-## Live Examples
+## Source code markup
-Here is how we do live examples. All examples here will point to other guides such as TOH-6 for convenience.
+You must add special code snippet markup to sample source code files before they can be displayed by `` and `` components.
-### Plain Live Example
+
-When a live example is included in a guide, it allows readers to run the example and download the code that the Author has placed in the content/examples folder for their respective guide. A plain live example looks like this: ` 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.
+
+` or `` as you did in an example above like this:
+
+```html
+
+// #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`.
+
+` to the page you generate links that run sample code in the Plunker live coding environment and download that code to the reader's file system.
+
+Live examples (AKA "plunkers") are defined by one or more `plnkr.json` files in the root of a code sample folder. Each sample folder usually has a single unnamed definition file, the default `plnkr.json`.
+
+
+
+You can create additional, named definition files in the form `name.plnkr.json`. See `content/examples/testing` for examples.
+
+The schema for a `plnkr.json` hasn't been documented yet but looking at the `plnkr.json` files in the example folders should tell you most of what you need to know.
+
+
+
+Adding `Custom label and tooltip
-To replace 'live-example' with a title, you can provide a title as shown here.
+Give the live example anchor a custom label and tooltip by setting the `title` attribute.
+
+` tags:
-Another way to display aletrnative text for 'live-example' is to include it in the body of the live-example. The effect is the same as when you use the title attribute.
+Live example with content label
```html
-Live Example Flesh & Blood
+Live example with content label
```
-### Live Example from Another Guide
+Live example from another guide
-Example of live-example from the router guide Live Example from the Router guide .
+To link to a plunker 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 other than Default for Guide
+Live Example for named plunker
+
+To link to a plunker defined by a named `plnkr.json` file, set the `plnkr` attribute. The following example links to the plunker defined by `second.plnkr.json` in the current guide's directory.
+
+Live Example without download
+
+To skip the download link, add the `noDownload` attribute
+
+Just the plunker
+
```html
-Just the plunker
```
-### Live Example with only Download
+Live Example with download-only
+
+To skip the live plunker link and only link to the download, add the `downloadOnly` attribute.
+
+Download only
+
```html
-Download only
```
-### Live Example with Embedded Plunkers
-Embedded Plunkrs have default image. img allows you to override the default image.
+
+
+By default, a live example link opens a plunker in a separate browser tab.
+You can embed the plunker within the guide page itself by adding the `embedded` attribute.
+
+For performance reasons, the plunker does not start right away. The reader sees an image instead. Clicking the image starts the sometimes-slow process of launching the embedded plunker within an iframe on the page.
+
+You usually replace the default plunker 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/plunker/unused/click-to-run.png`.
+
```html
-
- My location has been marked using {@ section-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`{@ name}` syntax like this.
+
+
+ {@a ugly-anchors}
+
+#### Ugly, long section header anchors
-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/dir-of-page with the relative path to the page that has the location that the reader should reach.
+Now [link to that custom anchor name](#ugly-anchors) as you did before.
+
```html
-[alternative text] (path-to-page/dir-of-page/#section-Anchors)
+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
-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. Note that the content of an alert is indented to the right by two spaces.
-
-
+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 very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful alert.
+A helpful, informational alert.
-
-Here is sample code to generate alerts.
+Here is the markup for these alerts.
```html
- A very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful 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
-Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention to important occasions. Unlike alerts, callouts are designed to display multi-line content.
-
-
+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
-
-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
+**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
-
-A VERY IMPORTANT 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
+**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
-
-A VERY HELPFUL 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
+**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
-
-
-Here is sample code to generate important callouts.
+Here is the markup for the first of these callouts.
```html
-
+
+A critical point
-
-A VERY IMPORTANT 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
+**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
```
+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 be used to represent heirarchial data. Here is an example.
+Trees can represent hierarchical data.
@@ -509,7 +956,7 @@ Trees can be used to represent heirarchial data. Here is an example.
-Here is the code for this tree.
+Here is the markup for this file tree.
```html
@@ -552,7 +999,7 @@ Here is the code for this tree.
## Tables
-Tables can be used to present tabular data as it relates to each other.
+Use HTML tables to present tabular data.
-
-
-
- Framework
-
-
-
- Task
-
-
-
- Speed
-
-
-
-
+ Framework
+ Task
+ Speed
+
-
-
- AngularJS
-
-
-
- Routing
-
-
-
- Fast
-
-
-
-
+ AngularJSRouting
+ Fast
+
-
+ Angular v2Routing
+
- Angular 2
-
+ *Faster*
+
+
+
+
+ Angular v4Routing
- Routing
+
+ **Fastest :)**
+
-
-
- Faster
-
-
-
-
-
-
-
- Angular 4
-
-
-
- Routing
-
-
-
- Fastest :)
-
-
-
-
-
+
-Here is code for this table.
+Here is the markup for this table.
```html
-table
- tr
- th Framework
- th Task
- th Speed
- tr
- td AngularJS
- td Routing
- td fast
- tr
- td Angular 2
- td Routing
- td faster
+
+
+
+
+ Framework
+ Task
+ Speed
+
+
+ AngularJSRouting
+ Fast
+
+
+ Angular v2Routing
+
+
+
+ *Faster*
+
+
+
+
+ Angular v4Routing
+
+
+ **Fastest :)**
+
+
+
+
```
## Images
-### Using Images
+Image location
-HTML should be used to declare images in the docs. Do not use the markdown \!\[\.\.\.\]\(\.\.\.\) shorthand.
+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.
-The HTML to use is an <img src="..." alt="..."> 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 is visible inline in the text.
+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"
```
-#### Floating Images
+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 `` tag, which styles the image within a drop-shadow frame. You'll need the editor's permission to skip the `` tag.
+
+Here's a conforming example
+
+
+
+
-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
-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:
+_Note that the HTML image element does not have a closing tag._
+
+Image dimensions
+
+The doc generator reads the image dimensions from the file and adds width and height attributes to the `img` tag automatically. If you want to control the size of the image, supply your own width and height attributes.
+
+Here's the "flying hero" at a more reasonable scale.
+
+
+
+
```html
+
+
+
+
+```
+
+Wide images can be a problem. Most browsers try to rescale the image but wide images may overflow the document in certain viewports.
+
+**Do not set a width greater than 700px**. If you wish to display a larger image, provide a link to the actual image that the user can click on to see the full size image separately as in this example of `source-map-explorer` output from the "Ahead-of-time Compilation" guide:
+
+
+
+
+
+
+
+Image compression
+
+Large image files can be slow to load, harming the user experience. Always compress the image.
+Consider using an image compression web site such as [tinypng](https://tinypng.com/ "tinypng").
+
+Floating images
+
+You can float the image to the left or right of text by applying the class="left" or class="right" attributes respectively.
+
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
+
+
+The markup for the above example is:
+
+```html
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break.
+
```
-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:
+Note that you generally don't wrap a floating image in a `` element.
+
+#### Floating within a subsection
+
+If you have a floating image inside an alert, callout, or a subsection, 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:
+
+
+
+
+
+ A subsection with **markdown** formatted text.
+
+
```html
-
- Some **markdown** formatted text.
+
+
+ A subsection with **markdown** formatted text.
-
-```
-
-#### 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.
-
- ![]()
-
-
-```
-
-
+```
\ No newline at end of file
diff --git a/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png
new file mode 100644
index 0000000000..22cd657e3e
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png differ
diff --git a/aio/content/images/guide/docs-style-guide/flying-hero.png b/aio/content/images/guide/docs-style-guide/flying-hero.png
new file mode 100644
index 0000000000..d8e43ea29a
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/flying-hero.png differ
diff --git a/aio/content/navigation.json b/aio/content/navigation.json
index 1008f8f9e7..b4c75e37c6 100644
--- a/aio/content/navigation.json
+++ b/aio/content/navigation.json
@@ -54,6 +54,13 @@
"hidden": true
},
+ {
+ "url": "guide/docs-style-guide",
+ "title": "Doc authors style guide",
+ "tooltip": "Style guide for documentation authors",
+ "hidden": true
+ },
+
{
"url": "guide/quickstart",
"title": "Getting Started",
ngcontent-pmm-5>Mister Fantastic
-_ngcontent-pmm-6>Losing Team
-Mister Fantastic
-Losing Team
-
-Docregions are not supported in JSON
+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.
-#### Example of a nested docregion:
-
- <code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero">
-</code-example>
+The current guidelines allow for a three-level navigation structure with two header levels. Don't add a third header level.
-<code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters">
-</code-example>
+
+
+
+## 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 `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 `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 page. + +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 `
+
+Unless otherwise noted, all code snippets in this page are derived from sample source code
+located in the `content/examples/docs-style-guide` directory.
+
+
+
+#### 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 10 or more 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.
+
+Code Tabs
Code tabs display code much like Code examples do. The added advantage is that they can display mutiple code samples within a tabbed interface. Each tab is displayed using Code-pane. -### Code-tabs Attributes +#### Code-tabs attributes -* linenums: true, false, display line numbers in the code in all tabs when the number of code statements are 10 or more +* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are are enabled only when code for a tab pane has 10 or more lines. -### Code-pane Attributes +#### Code-pane attributes -* path: a file in the content/examples folder -* title: seen in the header of a tab -* linenums: true, false, display line numbers for the code in this tab when the number of code statements are 10 or more +* `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 are enabled only when there are 10 or more lines. -The example below uses the source code for a small application that bundles with Webpack techniques. This will create multiple tabs, each with its own title and be 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. +The example below uses the source code for a small application that bundles with Webpack techniques. This creates multiple tabs, each with its own title and be 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.
-When a live example is included in a guide, it allows readers to run the example and download the code that the Author has placed in the content/examples folder for their respective guide. A plain live example looks like this:
+
+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 plunkers 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 `
+
+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 `
+
+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.
+
+
+
+You can create additional, named definition files in the form `name.plnkr.json`. See `content/examples/testing` for examples.
+
+The schema for a `plnkr.json` hasn't been documented yet but looking at the `plnkr.json` files in the example folders should tell you most of what you need to know.
+
+
+
+Adding `Custom label and tooltip
-To replace 'live-example' with a title, you can provide a title as shown here. +Give the live example anchor a custom label and tooltip by setting the `title` attribute. + +Live example from another guide
-Example of live-example from the router guideLive Example for named plunker
+ +To link to a plunker defined by a named `plnkr.json` file, set the `plnkr` attribute. The following example links to the plunker defined by `second.plnkr.json` in the current guide's directory. + +Live Example without download
+ +To skip the download link, add the `noDownload` attribute + +Live Example with download-only
+ +To skip the live plunker link and only link to the download, add the `downloadOnly` attribute. + +
+
+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`{@ name}` syntax like this.
+
+
+
+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
-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. Note that the content of an alert is indented to the right by two spaces.
-
-
+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.
-Here is sample code to generate alerts.
+Here is the markup for these alerts.
```html
- A very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful alert.
+A helpful, informational alert.
-
- A very critical alert.
+A critical alert.
- A very important alert.
+An important alert.
- A very helpful 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
-Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention to important occasions. Unlike alerts, callouts are designed to display multi-line content.
-
-
+Callouts (like alerts) are meant to draw attention to important points. Use a callout when you want a riveting header and multi-line content.
-
-Here is sample code to generate important callouts.
+Here is the markup for the first of these callouts.
```html
-
+A critical point
-
-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
+**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
-
-A VERY IMPORTANT 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
+**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
-
-A VERY HELPFUL 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
+**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 critical point
-
-A VERY IMPORTANT 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
+**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
```
+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 be used to represent heirarchial data. Here is an example.
+Trees can represent hierarchical data.
@@ -509,7 +956,7 @@ Trees can be used to represent heirarchial data. Here is an example.
-Here is the code for this tree.
+Here is the markup for this file tree.
```html
@@ -552,7 +999,7 @@ Here is the code for this tree.
## Tables
-Tables can be used to present tabular data as it relates to each other.
+Use HTML tables to present tabular data.
-
-Here is code for this table.
+Here is the markup for this table.
```html
-table
- tr
- th Framework
- th Task
- th Speed
- tr
- td AngularJS
- td Routing
- td fast
- tr
- td Angular 2
- td Routing
- td faster
+
+
+
+
```
## Images
-### Using Images
+ is visible inline in the text.
+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"
```
-#### Floating Images
+![]()
` tag.
+
+For accessibility, always set the `alt` attribute with a meaningful description of the image.
+
+You should nest the `![]()
` tag within a `` tag, which styles the image within a drop-shadow frame. You'll need the editor's permission to skip the `` tag.
+
+Here's a conforming example
+
+
+
+
-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
-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:
+_Note that the HTML image element does not have a closing tag._
+
+
+
+
```html
+
+
+
+
+```
+
+Wide images can be a problem. Most browsers try to rescale the image but wide images may overflow the document in certain viewports.
+
+**Do not set a width greater than 700px**. If you wish to display a larger image, provide a link to the actual image that the user can click on to see the full size image separately as in this example of `source-map-explorer` output from the "Ahead-of-time Compilation" guide:
+
+
+
+
+
+
+
+
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break. + +
+ +The markup for the above example is: + +```html +
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `
` where the text should break. +
``` -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: +Note that you generally don't wrap a floating image in a `` element.
+
+#### Floating within a subsection
+
+If you have a floating image inside an alert, callout, or a subsection, 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:
+
+
- ![]()
-
-
-```
-
-
+```
\ No newline at end of file
diff --git a/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png
new file mode 100644
index 0000000000..22cd657e3e
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/docs-style-guide-plunker.png differ
diff --git a/aio/content/images/guide/docs-style-guide/flying-hero.png b/aio/content/images/guide/docs-style-guide/flying-hero.png
new file mode 100644
index 0000000000..d8e43ea29a
Binary files /dev/null and b/aio/content/images/guide/docs-style-guide/flying-hero.png differ
diff --git a/aio/content/navigation.json b/aio/content/navigation.json
index 1008f8f9e7..b4c75e37c6 100644
--- a/aio/content/navigation.json
+++ b/aio/content/navigation.json
@@ -54,6 +54,13 @@
"hidden": true
},
+ {
+ "url": "guide/docs-style-guide",
+ "title": "Doc authors style guide",
+ "tooltip": "Style guide for documentation authors",
+ "hidden": true
+ },
+
{
"url": "guide/quickstart",
"title": "Getting Started",
| - Framework - | - -- Task - | - -- Speed - | - -Framework | +Task | +Speed | +
|---|---|---|---|
- AngularJS
- |
-
- - Routing - | - -
- Fast
- |
-
-AngularJS |
+ Routing | +Fast | +
Angular v2 |
+ Routing | +
- Angular 2
- |
+ *Faster*
+
+
+ |
Angular v4 |
+ Routing | - Routing + + **Fastest :)** + | - -
- Faster
- |
-
-
- Angular 4
- |
-
- - Routing - | - -
- Fastest :)
- |
-
-
| Framework | +Task | +Speed | +
|---|---|---|
AngularJS |
+ Routing | +Fast | +
Angular v2 |
+ Routing | + ++ + *Faster* + + | +
Angular v4 |
+ Routing | ++ + **Fastest :)** + + | +
Image location
-HTML should be used to declare images in the docs. Do not use the markdown \!\[\.\.\.\]\(\.\.\.\) shorthand. +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. -The HTML to use is an <img src="..." alt="..."> 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 hereUse the HTML <img> tag
+ +**Do not use the markdown image syntax, \!\[\.\.\.\]\(\.\.\.\).** + +Images should be specified in an `
+
+Image dimensions
+ +The doc generator reads the image dimensions from the file and adds width and height attributes to the `img` tag automatically. If you want to control the size of the image, supply your own width and height attributes. + +Here's the "flying hero" at a more reasonable scale. + +
+
+
+ Image compression
+ +Large image files can be slow to load, harming the user experience. Always compress the image. +Consider using an image compression web site such as [tinypng](https://tinypng.com/ "tinypng"). + +Floating images
+ +You can float the image to the left or right of text by applying the class="left" or class="right" attributes respectively. + +
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `` where the text should break. + +
+ +The markup for the above example is: + +```html +
+
+This text wraps around to the right of the floating "flying hero" image.
+
+Headings and code-examples automatically clear a floating image. If you need to force a piece of text to clear a floating image, add `` where the text should break. +
``` -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: +Note that you generally don't wrap a floating image in a `
+
+
+
+ A subsection with **markdown** formatted text.
+
+
```html
+
+ A subsection with **markdown** formatted text.
+
+
-
- Some **markdown** formatted text.
+
+
+ A subsection with **markdown** formatted text.
-
-```
-
-#### 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.
-
+
+ A subsection with **markdown** formatted text.