diff --git a/aio/content/examples/docs-style-guide/src/app/not-great.component.ts b/aio/content/examples/docs-style-guide/src/app/not-great.component.ts
new file mode 100644
index 0000000000..64f4f26492
--- /dev/null
+++ b/aio/content/examples/docs-style-guide/src/app/not-great.component.ts
@@ -0,0 +1,13 @@
+import { Component } from '@angular/core';
+
+@Component({
+ selector: 'app-not-great',
+})
+// #docregion not-great
+export class NotGreatComponent {
+
+ buggyFunction() {
+ // things could be better here...
+ }
+}
+// #enddocregion not-great
diff --git a/aio/content/guide/docs-style-guide.md b/aio/content/guide/docs-style-guide.md
index 017fd92fd7..446a46848f 100644
--- a/aio/content/guide/docs-style-guide.md
+++ b/aio/content/guide/docs-style-guide.md
@@ -1,150 +1,69 @@
# Angular documentation style guide
-
-This style guide is for anyone who contributes to the Angular documentation (this site).
-These guidelines should be followed by all authors.
-Deviations must be approved by a documentation editor.
+This style guide covers the standards for writing [Angular documentation on angular.io](https://angular.io/docs).
+These standards ensure consistency in writing style, Markdown conventions, and code snippets.
-The guidelines described here serve two purposes:
+## Prerequisites
-* To ensure a high-quality, consistent experience for Angular documentation users.
+Before contributing to the Angular documentation, it is helpful if you are familiar with the following:
-* To simplify the writing process for contributing authors.
-This guide helps you make decisions about tone, voice, and style.
-It also helps you find the right markup quickly.
+* `git`: for an introduction, see GitHub's [Git Handbook](https://guides.github.com/introduction/git-handbook/)
+* `GitHub`: for an introduction, see GitHub's [Hello World](https://guides.github.com/activities/hello-world/)
+* Markdown: see GitHub's [Mastering Markdown](https://guides.github.com/features/mastering-markdown/)
+* Angular coding style: see the [Angular Style Guide](guide/styleguide "Angular Application Code Style Guide")
+* Google writing style: The [Google Developer Documentation Style Guide](https://developers.google.com/style/) is a comprehensive resource that this Angular documentation style guide builds upon.
+## Kinds of Angular documentation
-
+The categories of Angular documentation include:
-This guide is a *living document*; it changes over time.
-We strive for consistency to the extent feasible, but you may find parts of our documentation that don't match this style guide.
-When in doubt, **follow this guide rather than imitating existing documents.**
+* [Guides](docs): much of what's in the [documentation section of angular.io](docs).
+Guides walk the reader step-by-step through tasks to demonstrate concepts and are often accompanied by a working example.
+These include [Getting Started](start), [Tour of Heroes](tutorial), and pages about [Forms](guide/forms-overview), [Dependency Injection](guide/dependency-injection), and [HttpClient](guide/http).
+Contributing members of the community and Angular team members maintain this documentation in [Markdown](https://daringfireball.net/projects/markdown/syntax "Markdown").
+* [API documentation](api): reference documents for the [Angular Application Programming Interface, or API](api).
+These are more succinct than guides and serve as a reference for Angular features.
+They are especially helpful for people already acquainted with Angular concepts.
+The [angular.io](https://angular.io/) infrastructure generates these documents from source code and comments that contributors edit.
+* [CLI documentation](cli): the [angular.io](https://angular.io/) infrastructure generates these documents from CLI source code.
-
-
-## Scope of these guidelines
-
-We ask all contributing authors to adhere to three aspects of style:
-
-
-* **Writing style:** Word usage, grammar, capitalization, and punctuation.
-Adherence to Angular's writing guidelines ensures a consistent "voice", helps ensure accuracy of the information, and facilitates use world-wide, by audiences with different backgrounds.
-
-
-* **Markup style:** How to include images, tables, alert boxes, and code snippets.
-Angular docs are written in Markdown, with custom extensions for this site. Correct markup ensures a consistent look-and-feel, and is essential for the doc to build and function correctly.
-
-
-* **Angular coding style:** Coding style for example apps and code snippets.
-Code examples are encouraged for demonstrating how to apply the concepts and features discussed.
-Angular has a custom framework that enables authors to include code snippets directly from example apps that are automatically tested as part of doc builds.
-To contribute example code, you must understand Angular itself and the custom framework for Angular doc examples.
-
-For each aspect of style, the following table explains where to find the primary guidelines and what this Angular Documentation Style Guide offers.
-
-
-Style | Guidelines
------------------------- | -------------------------------
-**Writing style** | Primary: [Google Developer Documentation Style Guide](https://developers.google.com/style/)
This guide: Specifies any special considerations for Angular docs.
-**Markup style** | Primary: This guide
This guide: Specifies guidelines for markup of guides and tutorials, which are written primarily in Markdown.
-**Angular coding style** | Primary: [Angular Style Guide](guide/styleguide "Angular Application Code Style Guide").
This guide: How to create, store, and include code examples in guides and tutorials.
-
-
-
-Note: Angular API and CLI reference docs are generated from source code and/or related source files, which may have other markup styles and other ways of including code examples.
-
-
-
-
-## Doc generation and tooling
-
-To make changes to the documentation pages and sample code, clone the [Angular github repository](https://github.com/angular/angular "Angular repo") and go to the `aio/` folder.
-
-The [aio/README.md](https://github.com/angular/angular/blob/master/aio/README.md "AIO ReadMe") explains how to install and use the tools to edit and test your changes.
-
-Here are a few essential commands for guide page authors.
-
-1. `yarn setup` — installs packages; builds docs, stackblitz, and zips.
-
-1. `yarn docs-watch --watch-only` — watches for saved content changes and refreshes the browser. The (optional) `--watch-only` flag skips the initial docs rebuild.
-
-1. `yarn start` — starts the doc viewer application so you can see your local changes in the browser.
-
-1. http://localhost:4200/ — browse to the app running locally.
-
-You can combine `yarn docs-watch` and `yarn start` into one command with `yarn serve-and-sync`.
-
-## Guide pages
-
- All but a few guide pages are [markdown](https://daringfireball.net/projects/markdown/syntax "markdown") files with an `.md` extension.
-
-Every guide page file is stored in the `content/guide` directory. Although the [side navigation](#navigation) panel displays as a hierarchy, the directory is flat with no sub-folders.
-The flat folder approach allows us to shuffle the apparent navigation structure without moving page files or redirecting old page URLs.
-
-The doc generation process consumes the markdown files in the `content/guide` directory and produces JSON files in the `src/generated/docs/guide` directory, which is also flat. Those JSON files contain a combination of document metadata and HTML content.
-
-The reader requests a page by its Page URL. The doc viewer fetches the corresponding JSON file, interprets it, and renders it as fully-formed HTML page.
-
-Page URLs mirror the `content` file structure. The URL for the page of a guide is in the form `guide/{page-name}`. The page for _this_ "Authors Style Guide" is located at `content/guide/docs-style-guide.md` and its URL is `guide/docs-style-guide`.
-
-
-
-
-_Tutorial_ pages are exactly like guide pages. The only difference is that they reside in `content/tutorial` instead of `content/guide` and have URLs like `tutorial/{page-name}`.
-
-_API_ pages are generated from Angular source code into the `src/generated/docs/api` directory.
-The doc viewer translates URLs that begin `api/` into requests for document JSON files in that directory. This style guide does not discuss creation or maintenance of API pages.
-
-_Marketing_ pages are similar to guide pages. They're located in the `content/marketing` directory. While they can be markdown files, they may be static HTML pages or dynamic HTML pages that render with JSON data.
-
-Only a few people are authorized to write marketing pages. This style guide does not discuss creation or maintenance of marketing pages.
-
-
## Markdown and HTML
-While documentation guide pages ultimately render as HTML, almost all of them are written in [markdown](https://daringfireball.net/projects/markdown/syntax "markdown").
+While the Angular guides are [Markdown](https://daringfireball.net/projects/markdown/syntax "Markdown") files, there are some sections within the guides that use HTML.
-Markdown is easier to read and to edit than HTML. Many editors (including Visual Studio Code) can render markdown as you type it.
+
-From time to time you'll have to step away from markdown and write a portion of the document in HTML. Markdown allows you to mix HTML and markdown in the same document.
-
-Standard markdown processors don't allow you to put markdown _within_ HTML tags. But the Angular documentation markdown processor **supports markdown within HTML**, as long as you follow one rule:
-
-
-
-**Always** follow every opening and closing HTML tag with _a blank line_.
+ To enable HTML in an Angular guide, **always** follow every opening and closing HTML tag with a blank line.
+Notice the required blank line after the opening `
` in the following example:
+
```html
-
+
**Always** follow every opening and closing HTML tag with _a blank line_.
```
-
-
- It is customary but not required to _precede_ the _closing HTML_ tag with a blank line as well.
-
-
+It is customary but not required to precede the closing HTML tag with a blank line as well.
## Title
-Every guide document must have a title.
+Every guide document must have a title, and it should appear at the top of the page.
-The title should appear at the top of the physical page.
-Begin the title with the markdown `#` character. Alternatively, you can write the equivalent `
`.
+Begin the title with the Markdown `#` character, which renders as an `` in the browser.
```html
# Angular documentation style guide
```
-**Only one title (``) per document!**
+**A document can have only one ``.**
-Title text should be in "Sentence case", which means the first word is capitalized and all other words are lower case (unless they are technical terms that are always capitalized, like "Angular").
+Title text should be in _Sentence case_, which means the first word is capitalized and all other words are lower case.
+Technical terms that are always capitalized, like "Angular", are the exception.
```html
# Deprecation policy in Angular
@@ -152,91 +71,100 @@ Title text should be in "Sentence case", which means the first word is capitaliz
**Always follow the title with at least one blank line.**
-Note that the corresponding left-nav TOC text should be in "title case", which means that you use capital letters to start the first words and all principal words. Use lower case letters for secondary words such as "in", "of", and "the". The TOC title can also be shortened to fit in the column.
+The corresponding text in the left nav is in _Title Case_, which means that you use capital letters to start the first words and all principal words.
+Use lower case letters for secondary words such as "in", "of", and "the".
+You can also shorten the nav title to fit in the column.
## Sections
-A typical document is divided into sections.
+A typical document has sections.
-All heading text should be in "Sentence case", which means the first word is capitalized and all other words are lower case.
+All section headings are 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.**
+**Always follow a section heading with at least one blank line.**
+
+### Main section heading
-
-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.
+Begin a main section heading with the Markdown `##` characters, which renders as an `` in the browser.
-The main section heading should be followed by a blank line and then the content for that heading.
+Follow main section headings with a blank line and then the content for that heading as in the following example:
```html
- ## Sections
+ ## Main section heading
- A typical document is divided into sections.
+ Content after a blank line.
```
-
-Secondary section heading
-
+### Secondary section heading
-A secondary section heading is related to a main heading and _falls textually within_ the bounds of that main 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.
+Begin a secondary heading with the Markdown `###` characters, which renders as an `` in the browser.
-The secondary heading should be followed by a blank line and then the content for that heading.
+Follow a secondary heading by a blank line and then the content for that heading as in the following example:
```html
### Secondary section heading
- A secondary section ...
+ Content after a blank line.
```
-#### Additional section headings
+### 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.
+While you can use additional section headings, the [Table-of-contents (TOC)](#table-of-contents) generator only shows `` and `` headings in the TOC on the right of the page.
```html
- #### Additional section headings
+ #### The TOC won't display this
- Try to minimize ...
+ Content after a blank line.
```
## 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.
+Most pages display a table of contents or TOC.
+The TOC appears in the right panel when the viewport is wide.
+When narrow, the TOC appears in a collapsible region near the top of the page.
-You should not create your own TOC by hand. The TOC is generated automatically from the page's main and secondary section headers.
+You don't need to create your own TOC by hand because the TOC generator creates one automatically from the page's `` and `` 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.
+To exclude a heading from the TOC, create the heading as an `` or `` element with a class called 'no-toc'.
```html
+
This heading is not displayed in the TOC
+
```
-You can turn off TOC generation for the _entire_ page by writing the title with an `` tag and the `no-toc` class.
+You can turn off TOC generation for the entire page by writing the title with an `` tag and the `no-toc` class.
```html
+
A guide without a TOC
+
```
## Navigation
-The navigation links at the top, left, and bottom of the screen are generated from the JSON configuration file, `content/navigation.json`.
+To generate the navigation links at the top, left, and bottom of the screen, use the JSON configuration file, `content/navigation.json`.
-The authority to change the `navigation.json` file is limited to a few core team members.
-But for a new guide page, you should suggest a navigation title and position in the left-side navigation panel called the "side nav".
+
-Look for the `SideNav` node in `navigation.json`. The `SideNav` node is an array of navigation nodes. Each node is either an _item_ node for a single document or a _header_ node with child nodes.
+If you have an idea that would result in navigation changes, [file an issue](https://github.com/angular/angular/issues/new/choose) first so that the Angular team and community can discuss the change.
-Find the header for your page. For example, a guide page that describes an Angular feature is probably a child of the `Fundamentals` header.
+
+
+For a new guide page, edit the `SideNav` node in `navigation.json`.
+The `SideNav` node is an array of navigation nodes.
+Each node is either an item node for a single document or a header node with child nodes.
+
+Find the header for your page.
+For example, a guide page that describes an Angular feature is probably a child of the `Fundamentals` header.
```html
{
@@ -246,57 +174,50 @@ Find the header for your page. For example, a guide page that describes an Angul
}
```
-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.
+A header node child can be an item node or another header node.
+If your guide page belongs under a sub-header, find that sub-header in the JSON.
-Add an _item_ node for your guide page as a child of the appropriate _header_ node. It probably looks something like this one.
+Add an item node for your guide page as a child of the appropriate header node as in the following example:
```html
-{
- "url": "guide/architecture",
- "title": "Architecture",
- "tooltip": "The basic building blocks of Angular applications."
-}
+ {
+ "url": "guide/docs-style-guide",
+ "title": "Doc authors style guide",
+ "tooltip": "Style guide for documentation authors.",
+ },
```
A navigation node has the following properties:
-* `url`- the URL of the guide page (_item node only_).
+* `url`: the URL of the guide page, which is an item node only.
-* `title`- the text displayed in the side nav.
+* `title`: the text displayed in the side nav.
-* `tooltip` - text that appears when the reader hovers over the navigation link.
+* `tooltip`: text that appears when the reader hovers over the navigation link.
-* `children` - an array of child nodes (_header node only_).
-
-* `hidden` - defined and set true if this is a guide page that should _not_ be displayed in the navigation panel. Rarely needed, it is a way to hide the page from navigation while making it available to readers who should know about it. _This_ "Authors Style Guide" is a hidden page.
+* `children`: an array of child nodes, which is a header node only.
+* `hidden`: defined and set `true` if this is a guide page that should not be displayed in the navigation panel.
-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.
+Do not create a node that is both a header and an item node by specifying the `url` property of a header node.
-
-
-
-The current guidelines allow for a three-level navigation structure with two header levels. Don't add a third header level.
-
-
-
-
## Code snippets
-Guides are rich in examples of working Angular code. Example code can be commands entered in a terminal window, a fragment of TypeScript or HTML, or an entire code file.
+[Angular.io](https://angular.io/docs) has a custom framework that enables authors to include code snippets directly from working example apps that are automatically tested as part of documentation builds.
-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.
+In addition to working code snippets, example code can include terminal commands, a fragment of TypeScript or HTML, or an entire code file.
+Whatever the source, the doc viewer renders them as code snippets, either individually with the [code-example](#code-example "code-example") component or as a tabbed collection with the [code-tabs](#code-tabs "code-tabs") component.
{@a code-example}
-### Code example
+### When to use code font
-You can display a simple, inline code snippet with the markdown backtick syntax.
+You can display a minimal, inline code snippet with the Markdown backtick syntax.
Use a single backtick on either side of a term when referring to code or the
name of a file in a sentence.
The following are some examples:
@@ -305,115 +226,106 @@ The following are some examples:
* The `name` property is `Sally`.
* Add the component class name to the `declarations` array.
-The markdown is as follows:
+The Markdown is as follows:
-```markdown
+```md
* In the `app.component.ts`, add a `logger()` method.
* The item property is `true`.
* Add the component class name to the `declarations` array.
```
-In certain cases, when you apply backticks around a term, it may auto-link to
-the API documentation. If you do not intend the term to be a link, use the following
-syntax:
+
+### Auto-linking in code snippets
+
+In certain cases, when you apply backticks around a term, it may auto-link to the API documentation.
+If you do not intend the term to be a link, use the following syntax:
```html
The item property is `true`.
```
-For block code snippets, we generally prefer to display code with
-the Angular documentation _code-example_ component represented by the `` tag.
-The `` tag has a `header` attribute that you use to identify the file that the example comes from. The header should be used whenever possible to establish the context of the example.
-See [Code snippets and code examples](guide/docs-style-guide#code-snippets-and-code-samples) for more details.
+### Hard-coded snippets
-Inline code-snippets
+Ideally, you should source code snippets [from working sample code](#from-code-samples), though there are times when an inline snippet is necessary.
-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.
+For terminal input and output, place the content between `` tags, set the CSS class to `code-shell`, and set the language attribute to `sh` as in this example:
+
npm start
+
```html
+
npm start
+
```
-Inline, hand-coded snippets like this one are _not_ testable and, therefore, are intrinsically unreliable.
-This example belongs to the small set of pre-approved, inline snippets that includes
-user input in a command shell or the _output_ of some process.
+Inline, hard-coded snippets like this one are not testable and, therefore, intrinsically unreliable.
+This example belongs to the small set of pre-approved, inline snippets that includes user input in a command shell or the output of some process.
-**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.
-For hypothetical examples such as illustrations of configuration options in a JSON file, you should still use The `` tag with the `header` attribute to identify the context.
+For hypothetical examples such as illustrations of configuration options in a JSON file, use the `` tag with the `header` attribute to identify the context.
{@a from-code-samples}
-Code snippets and code samples
+### Compilable example apps
-One of the documentation design goals is that guide page code snippets should be examples of real, working code.
+One of the Angular documentation design goals is that guide page code snippets be examples of working code.
-We meet this goal by displaying code snippets that are derived directly from standalone code samples, written specifically for these guide pages.
+Authors meet this goal by displaying code snippets directly from working sample apps, written specifically for these guide pages.
-The author of a guide page is responsible for the code sample that supports that page.
-The author must also write end-to-end tests for the sample.
-
-Code samples are located in sub-folders of the `content/examples` directory of the `angular/angular` repository. An example folder name should be the same as the guide page it supports.
+Find sample apps in sub-folders of the `content/examples` directory of the `angular/angular` repository.
+An example folder name is often the same as the guide page it supports.
-A guide page might not have its own sample code. It might refer instead to a sample belonging to another page.
+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.
+The Angular CI process runs all end-to-end tests for every Angular PR.
+Angular re-tests the samples after every new version of a sample and every new version of Angular.
-When possible, every snippet of code on a guide page should be derived from a code sample file. You tell the Angular documentation engine which code file - or fragment of a code file - to display by configuring `` attributes.
+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
+{@a display-whole-file}
-_This_ "Authors Doc Style Guide" has its own sample application, located in the `content/examples/docs-style-guide` folder.
+### Displaying an entire code file
-The following _code-example_ displays the sample's `app.module.ts`.
+This Angular documentation style guide that you are currently reading has its own example application, located in the `content/examples/docs-style-guide` folder.
+
+The following `` displays the sample's `app.module.ts`:
-Here's the brief markup that produced that lengthy snippet:
+The following markup produces that snippet:
```html
-
+
```
-You identified the snippet's source file by setting the `path` attribute to sample folder's location _within_ `content/examples`.
+The `path` attribute identifies the snippet's source file at the example app folder's location within `content/examples`.
In this example, that path is `docs-style-guide/src/app/app.module.ts`.
-You added a header to tell the reader where to find the file by setting the `header` attribute.
-Following convention, you set the `header` attribute to the file's location within the sample's root folder.
+The header tells the reader where to find the file.
+Following convention, set the `header` attribute to the file's location within the example app's root folder.
-
-
-Unless otherwise noted, all code snippets in this page are derived from sample source code
-located in the `content/examples/docs-style-guide` directory.
-
-
+Unless otherwise noted, all code snippets in this page are from sample source code located in the `content/examples/docs-style-guide` directory.
-The doc tooling reports an error if the file identified in the path does not exist **or is _git_-ignored**.
+The documentation tooling reports an error if the file identified in the path does not exist or is in the [`.git-ignore` file](https://github.com/angular/angular/blob/master/aio/content/examples/.gitignore).
+Most `.js` files are in `.git-ignore`.
-Most `.js` files are _git_-ignored.
-If you want to include an ignored code file in your project and display it in a guide you must _un-ignore_ it.
-
-The preferred way to un-ignore a file is to update the `content/examples/.gitignore` like this:
+To include an ignored code file in your project and display it in a guide, remove it from `.git-ignore`. Update the `content/examples/.gitignore` as follows:
# my-guide
@@ -423,38 +335,20 @@ The preferred way to un-ignore a file is to update the `content/examples/.gitign
-#### 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.
-
-* `header`- 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 default to `false` (i.e. no line numbers are displayed). 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
+### Displaying part of a code file
-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.
+To include a snippet of code within a sample code file, rather than the entire file, use the `` `region` attribute.
+The following example focuses on the `AppModule` class and its `@NgModule()` metadata:
-First you surround that fragment in the source file with a named _docregion_ as described [below](#source-code-markup).
-Then you reference that _docregion_ in the `region` attribute of the `` like this
-
+To render the above example, the HTML in the Markdown file is as follows:
```html
```
-A couple of observations:
+The `path` points to the file, just as in examples that render the [entire file](guide/docs-style-guide#display-whole-file).
+The `region` attribute specifies a portion of the source file delineated by an opening `#docregion` and a closing `#enddocregion`.
-1. The `region` value, `"class"`, is the name of the `#docregion` in the source file. Confirm that by looking at `content/examples/docs-style-guide/src/app/app.module.ts`
+You can see the `class` `#docregion` in the source file below.
+Notice the commented lines `#docregion` and `#enddocregion` in `content/examples/docs-style-guide/src/app/app.module.ts` with the name `class`.
-1. Omitting the `header` is fine when the source of the fragment is obvious. We just said that this is a fragment of the `app.module.ts` file which was displayed immediately above, in full, with a header.
-There's no need to repeat the header.
+
-#### Example of bad code
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { FormsModule } from '@angular/forms';
-Sometimes you want to display an example of bad code or bad design.
+import { AppComponent } from './app.component';
-You should be careful. Readers don't always read carefully and are likely to copy and paste your example of bad code in their own applications. So don't display bad code often.
+// #docregion class
+@NgModule({
+ imports: [ BrowserModule, FormsModule ],
+ declarations: [ AppComponent ],
+ bootstrap: [ AppComponent ]
+})
+export class AppModule { }
+// #enddocregion class
-When you do, set the `class` to `avoid`. The code snippet will be framed in bright red to grab the reader's attention.
+
+
+The opening and ending `#docregion` lines designate any lines of code between them as being included in the code snippet.
+This is why the import statements outside of the `class` `#docregion` are not in the code snippet.
+
+For more information on how to prepare example app files for use in guides, see
+ [Source code markup](#source-code-markup).
+
+### Code snippet options
+
+Specify the `` output with the following attributes:
+
+* `path`: the path to the file in the `content/examples` folder.
+
+* `header`: the header of the code listing.
+ This is the title of the code snippet and can include the path and extra information such as whether the snippet is an excerpt.
+
+* `region`: displays the source file fragment with that region name; regions are identified by `#docregion` markup in the source file.
+ See [Displaying a code snippet](#region "Displaying a code snippet").
+
+* `linenums`: value may be `true`, `false`, or a `number`.
+ The default is `false`, which means that the browser displays no line numbers.
+ The `number` option starts line numbering at the given value.
+ For example, `linenums=4` sets the starting line number to 4.
+
+* `class`: code snippets can be styled with the CSS classes `no-box`, `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 applies to hard-coded examples.
+
+### Displaying bad code
+
+Occasionally, you want to display an example of less than ideal code or design, such as with **avoid** examples in the [Angular Style Guide](guide/styleguide).
+Because it is possible for readers to copy and paste examples of inferior code in their own applications, try to minimize use of such code.
+
+In cases where you need unacceptable examples, you can set the `class` to `avoid` or have the word `avoid` in the filename of the source file.
+By putting the word `avoid` in the filename or path, the documentation generator automatically adds the `avoid` class to the ``.
+Either of these options frames the code snippet in bright red to grab the reader's attention.
Here's the markup for an "avoid" example in the
-[_Angular Style Guide_](guide/styleguide#style-05-03 "Style 05-03: components as elements").
+[Angular Style Guide](guide/styleguide#style-05-03 "Style 05-03: components as elements") that uses the word `avoid` in the path name:
```html
```
+Having the word "avoid" in the file name causes the browser to render the code snippet with a red header and border:
+
+Alternatively, the HTML could include the `avoid` class as in the following:
+
+```html
+
+
+```
+
+Explicitly applying the class `avoid` causes the same result of a red header and red border:
+
+
+
+
+
{@a code-tabs}
+
### Code Tabs
-Code tabs display code much like _code examples_ do. The added advantage is that they can display multiple code samples within a tabbed interface. Each tab is displayed using _code pane_.
+Code tabs display code much like `code-examples` with the added advantage of displaying multiple code samples within a tabbed interface.
+Each tab displays code using a `code-pane`.
-#### Code-tabs attributes
+#### `code-tabs` attributes
-* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, it defaults to `false`.
+* `linenums`: The value can be `true`, `false`, or a number indicating the starting line number.
+The default is `false`.
-#### Code-pane attributes
+#### `code-pane` attributes
-* `path` - a file in the content/examples folder
-* `header` - 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, it defaults to `false`.
+* `path`: a file in the `content/examples` folder
+* `header`: what displays in the header of a tab
+* `linenums`: overrides the `linenums` property at the `code-tabs` level for this particular pane.
+The value can be `true`, `false`, or a number indicating the starting line number.
+The default is `false`.
-The next example displays multiple code tabs, each with its own header.
-It demonstrates control over display of line numbers at both the `` and `` levels.
+The following example displays multiple code tabs, each with its own header.
+It demonstrates showing line numbers in `` and ``.
+
@@ -529,12 +497,11 @@ It demonstrates control over display of line numbers at both the `` a
header="package.json (scripts)"
path="docs-style-guide/package.1.json">
+
-Here's the markup for that example.
-
-Note how the `linenums` attribute in the `` explicitly enables numbering for all panes.
-The `linenums` attribute in the second pane disables line numbering for _itself only_.
+The `linenums` attribute set to `true` on `` explicitly enables numbering for all panes.
+However, the `linenums` attribute set to `false` in the second `` disables line numbering only for itself.
```html
@@ -561,24 +528,24 @@ The `linenums` attribute in the second pane disables line numbering for _itself
{@a source-code-markup}
-## Source code markup
+## Preparing source code for code snippets
-You must add special code snippet markup to sample source code files before they can be displayed by `` and `` components.
+To display `` and `` snippets, add code snippet markup to sample source code files.
-The sample source code for this page, located in `context/examples/docs-style-guide`, contains examples of every code snippet markup described in this section.
+The sample source code for this page, located in `content/examples/docs-style-guide`, contains examples of every code snippet markup described in this section.
-Code snippet markup is always in the form of a comment. Here's the default _docregion_ markup for a TypeScript or JavaScript file:
+Code snippet markup is always in the form of a comment.
+The default `#docregion` markup for a TypeScript or JavaScript file is as follows:
```
// #docregion
-... some code ...
+... some TypeScript or JavaScript code ...
// #enddocregion
```
-Different file types have different comment syntax so adjust accordingly.
```html
@@ -592,60 +559,53 @@ Different file types have different comment syntax so adjust accordingly.
/* #enddocregion */
```
-The doc generation process erases these comments before displaying them in the doc viewer.
-It also strips them from stackblitz and sample code downloads.
+The documentation generation process erases these comments before displaying them in the documentation viewer, StackBlitz, and sample code downloads.
-Code snippet markup is not supported in JSON files because comments are forbidden in JSON files.
-See [below](#json-files) for details and workarounds.
+Because JSON does not allow comments, code snippet markup doesn't work in JSON files.
+See the section on [JSON files](#json-files) for more information.
+### `#docregion`
-#### _#docregion_
+Use `#docregion` in source files to mark code for use in `` or `` components.
-The _#docregion_ is the most important kind of code snippet markup.
+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 `` and `` components won't display a source code file unless it has a _#docregion_.
+The following `src/main.ts` is a an example of a file with a single `#docregion` at the top of the file.
-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_.
+
-
+As a result, the entire file is in the ``.
-The `src/main.ts` is a simple example of a file with a single _#docregion_ at the top of the file.
-
+### Naming a `#docregion`
-
-
-#### 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.
+To display multiple snippets from different fragments within the same file, give each fragment its own `#docregion` name as follows, where `your-region-name` is a hyphenated lowercase string:
```
-// #docregion region-name
+// #docregion your-region-name
... some code ...
-// #enddocregion region-name
+// #enddocregion your-region-name
```
-Remember to refer to this region by name in the `region` attribute of the `` or `` as you did in an example above like this:
+Reference this region by name in the `region` attribute of the `` or `` as follows:
```html
+ path="your-example-app/src/app/your-file.ts"
+ region="your-region-name">
```
-The _#docregion_ with no name is the _default region_. Do _not_ set the `region` attribute when referring to the default _#docregion_.
+Because the `#docregion` with no name is the default region, you do not need to set the `region` attribute when referring to the default `#docregion`.
-#### Nested _#docregions_
+### Nesting a `#docregion`
+
+Place a `#docregion` within another `#docregion` as in the following example with a nested `inner-region`:
-You can nest _#docregions_ within _#docregions_
```
// #docregion
... some code ...
@@ -655,22 +615,16 @@ You can nest _#docregions_ within _#docregions_
... yet more code ...
/// #enddocregion
```
-
-The `src/app/app.module.ts` file has a good example of a nested region.
+### Combining code fragments
-
+Combine several fragments from the same file into a single code snippet by defining multiple `#docregion` sections with the same region name.
+The following example defines two nested `#docregion` sections.
-#### Combining fragments
+The inner region, `class-skeleton`, appears twice—once to capture the code that opens the class definition and a second time to capture the code that closes the class definition.
-You can combine several fragments from the same file into a single code snippet by defining
-multiple _#docregions_ with the _same region name_.
+
-Examine the `src/app/app.component.ts` file which defines two nested _#docregions_.
-
-The inner, `class-skeleton` region appears twice, once to capture the code that opens the class definition and once to capture the code that closes the class definition.
-
-
// #docplaster
...
// #docregion class, class-skeleton
@@ -686,66 +640,82 @@ export class AppComponent {
// #docregion class-skeleton
}
// #enddocregion class, class-skeleton
+
-Here's are the two corresponding code snippets displayed side-by-side.
+The `#docplaster` marker tells the processor what text string to use—that is, the "plaster"—to join each of the fragments into a single snippet.
+Place the "plaster" text on the same line.
+For example, `#docplaster ---` would use `---` as the "plaster" text.
+In the case of the previous file, the "plaster" text is empty so there will be nothing in between each fragment.
+
+Without `#docplaster`, the processor inserts the default plaster—an ellipsis comment—between the fragments.
+
+Here are the two corresponding code snippets for side-by-side comparison.
-
+
+
+
-
+
+
+
-Some observations:
+The above example also demonstrates that one `#docregion` or `#enddocregion` comment can specify two region names, which is a convenient way to start or stop multiple regions on the same code line.
+Alternatively, you could put these comments on separate lines as in the following example:
-* 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_.
+// #docplaster
+...
+// #docregion class
+// #docregion class-skeleton
+export class AppComponent {
+// #enddocregion class-skeleton
+ title = 'Authors Style Guide Sample';
+ heroes = HEROES;
+ selectedHero: Hero;
- 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.
+ onSelect(hero: Hero): void {
+ this.selectedHero = hero;
+ }
+// #docregion class-skeleton
+}
+// #enddocregion class
+// #enddocregion class-skeleton
-* 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
+### JSON files
-Code snippet markup is not supported for JSON files because comments are forbidden in JSON files.
+The `` component cannot display portions of a JSON file because JSON forbids comments.
+However, you can display an entire JSON file by referencing it in the `` `src` attribute.
-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.
+For large JSON files, you could copy the nodes-of-interest into Markdown backticks, but as it's easy to mistakenly create invalid JSON that way, consider creating a JSON partial file with the fragment you want to display.
-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.
+You can't test a partial file nor use it in the application, but at least your editor can confirm that it is syntactically correct.
+You can also store the partial file next to the original, so it is more likely that the author will remember to keep the two in sync.
Here's an example that excerpts certain scripts from `package.json` into a partial file named `package.1.json`.
-
+
```html
-
+
```
-#### Partial file naming
+In some cases, it is preferable to use the name of the full file rather than the partial.
+In this case, the full file is `package.json` and the partial file is `package.1.json`.
+Since the focus is generally on the full file rather than the partial, using the name of the file the reader edits, in this example `package.json`, clarifies which file to work in.
-Many guides tell a story. In that story, the app evolves incrementally, often with simplistic or incomplete code along the way.
+### Partial file naming
-To tell that story in code, you'll often need to create partial files or intermediate versions of the final source code file with fragments of code that don't appear in the final app.
+The step-by-step nature of the guides necessitate refactoring, which means there are code snippets that evolve through a guide.
-Such partial and intermediate files need their own names.
-Follow the doc sample naming convention. Add a number before the file extension as illustrated here:
+Use partial files to demonstrate intermediate versions of the final source code with fragments of code that don't appear in the final app.
+The sample naming convention adds a number before the file extension, as follows:
```html
package.1.json
@@ -753,175 +723,187 @@ app.component.1.ts
app.component.2.ts
```
-You'll find many such files among the samples in the Angular documentation.
+Remember to exclude these files from StackBlitz by listing them in the `stackblitz.json` as illustrated here:
-Remember to exclude these files from stackblitz by listing them in the `stackblitz.json` as illustrated here.
+
-
{@a live-examples}
+
## Live examples
-By adding `` to the page you generate links that run sample code in the Stackblitz live coding environment and download that code to the reader's file system.
+Adding `` to a page generates two default links: .
-Live examples (AKA "stackblitz") are defined by one or more `stackblitz.json` files in the root of a code sample folder. Each sample folder usually has a single unnamed definition file, the default `stackblitz.json`.
+The first is a link to the StackBlitz example, which the default `stackblitz.json` file defines.
+You can find the `stackblitz.json` file in the `content/examples/example-app` directory, where `example-app` is the sample application folder you're using for the guide.
-
+By default, the documentation generator uses the name of the guide as the name of the example.
+So, if you're working on `router.md`, and use `` in the document, the documentation generator looks for `content/examples/router`.
+Clicking this link opens the code sample on StackBlitz in a new browser tab.
-You can create additional, named definition files in the form `name.stackblitz.json`. See `content/examples/testing` for examples.
+The second link downloads the sample app.
-The schema for a `stackblitz.json` hasn't been documented yet but looking at the `stackblitz.json` files in the example folders should tell you most of what you need to know.
+Define live examples by one or more `stackblitz.json` files in the root of a code sample folder.
+Each sample folder usually has a single unnamed definition file, the default `stackblitz.json`.
-
+### Live Example for named StackBlitz
-Adding `` to the page generates the two default links.
+You can create additional, named definition files in the form `name.stackblitz.json`.
+The [Testing](guide/testing) guide (`aio/content/guide/testing.md`) references a named StackBlitz file as follows:
-
+ ```html
+ Tests
+ ```
-1. a link to the Stackblitz defined by the default `stackblitz.json` file located in the code sample folder with the same name as the guide page.
+The `stackblitz` attribute value of `specs` refers to the `examples/testing/specs.stackblitz.json` file.
+If you were to leave out the `stackblitz` attribute, the default would be `examples/testing/stackblitz.json`.
-2. a link that downloads that sample.
+### Custom label and tooltip
-Clicking the first link opens the code sample on StackBlitz in a new browser tab.
-
-You can change the appearance and behavior of the live example with attributes and classes.
-
-
-Custom label and tooltip
-
-Give the live example anchor a custom label and tooltip by setting the `title` attribute.
-
-
+Change the appearance and behavior of the live example with attributes and classes.
+The following example gives the live example anchor a custom label and tooltip by setting the `title` attribute:
```html
```
+The browser renders the following:
+
+
+
You can achieve the same effect by putting the label between the `` tags:
-Live example with content label
-
```html
Live example with content label
```
-Live example from another guide
+The browser renders the following:
-To link to a Stackblitz in a folder whose name is not the same as the current guide page, set the `name` attribute to the name of that folder.
+Live example with content label
-Live Example from the Router guide
+### Live example from another guide
+
+To link to an example in a folder where the name is not the same as the current guide page, set the `name` attribute to the name of that folder.
+
+For example, to include the [Router](guide/router) guide example in this style guide, set the `name` attribute to `router`, that is, the name of the folder where that example resides.
```html
-Live Example from the Router guide
+Live example from the Router guide
```
-Live Example for named Stackblitz
+Live example from the Router guide
-To link to a Stackblitz defined by a named `stackblitz.json` file, set the `stackblitz` attribute. The following example links to the Stackblitz defined by `second.stackblitz.json` in the current guide's directory.
-
+### Live Example without download
+
+To omit the download link, add the `noDownload` attribute.
```html
-
+Just the StackBlitz
```
-Live Example without download
+The browser renders the following:
-To skip the download link, add the `noDownload` attribute.
+Just the StackBlitz
-Just the Stackblitz
-```html
-Just the Stackblitz
-```
+### Live Example with download-only
-Live Example with download-only
-
-To skip the live Stackblitz link and only link to the download, add the `downloadOnly` attribute.
-
-Download only
+To omit the live StackBlitz link and only link to the download, add the `downloadOnly` attribute.
```html
Download only
```
-Embedded live example
+The browser renders the following:
-By default, a live example link opens a Stackblitz in a separate browser tab.
-You can embed the Stackblitz within the guide page itself by adding the `embedded` attribute.
+Download only
-For performance reasons, the Stackblitz does not start right away. The reader sees an image instead. Clicking the image starts the sometimes-slow process of launching the embedded Stackblitz within an iframe on the page.
-Here's an embedded live example for this guide.
+### Embedded live example
+
+By default, a live example link opens a StackBlitz example in a separate browser tab.
+You can embed the StackBlitz example within the guide page by adding the `embedded` attribute.
+
+For performance reasons, StackBlitz does not start right away.
+Instead, the `` component renders an image.
+Clicking the image starts the process of launching the embedded StackBlitz within an `