Skip to content

Commit 42289f2

Browse files
josmar-crwdstffngthePunderWoman
josmar-crwdstffng
authored and
thePunderWoman
committed
docs: improve markdown (#45325)
The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
1 parent 7a37fe9 commit 42289f2

File tree

210 files changed

+18805
-23917
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

210 files changed

+18805
-23917
lines changed

‎aio/content/cli/index.md‎

Lines changed: 46 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,40 +7,47 @@ The Angular CLI is a command-line interface tool that you use to initialize, dev
77
Major versions of Angular CLI follow the supported major version of Angular, but minor versions can be released separately.
88

99
Install the CLI using the `npm` package manager:
10-
<code-example language="bash">
11-
npm install -g @angular/cli
10+
11+
<code-example format="shell" language="shell">
12+
13+
npm install -g &commat;angular/cli
14+
1215
</code-example>
1316

14-
For details about changes between versions, and information about updating from previous releases,
15-
see the Releases tab on GitHub: https://github.com/angular/angular-cli/releases
17+
For details about changes between versions, and information about updating from previous releases, see the Releases tab on GitHub: https://github.com/angular/angular-cli/releases
1618

1719
## Basic workflow
1820

1921
Invoke the tool on the command line through the `ng` executable.
2022
Online help is available on the command line.
21-
Enter the following to list commands or options for a given command (such as [generate](cli/generate)) with a short description.
23+
Enter the following to list commands or options for a given command \(such as [generate](cli/generate)\) with a short description.
24+
25+
<code-example format="shell" language="shell">
2226

23-
<code-example language="bash">
2427
ng help
2528
ng generate --help
29+
2630
</code-example>
2731

2832
To create, build, and serve a new, basic Angular project on a development server, go to the parent directory of your new workspace use the following commands:
2933

30-
<code-example language="bash">
34+
<code-example format="shell" language="shell">
35+
3136
ng new my-first-project
3237
cd my-first-project
3338
ng serve
39+
3440
</code-example>
3541

3642
In your browser, open http://localhost:4200/ to see the new application run.
3743
When you use the [ng serve](cli/serve) command to build an application and serve it locally, the server automatically rebuilds the application and reloads the page when you change any of the source files.
3844

3945
<div class="alert is-helpful">
4046

41-
When you run `ng new my-first-project` a new folder, named `my-first-project`, will be created in the current working directory. Since you want to be able to create files inside that folder, make sure you have sufficient rights in the current working directory before running the command.
47+
When you run `ng new my-first-project` a new folder, named `my-first-project`, will be created in the current working directory.
48+
Since you want to be able to create files inside that folder, make sure you have sufficient rights in the current working directory before running the command.
4249

43-
If the current working directory is not the right place for your project, you can change to a more appropriate directory by running `cd <path-to-other-directory>` first.
50+
If the current working directory is not the right place for your project, you can change to a more appropriate directory by running `cd <path-to-other-directory>` first.
4451

4552
</div>
4653

@@ -58,52 +65,68 @@ You can edit the generated files directly, or add to and modify them using CLI c
5865
Use the [ng generate](cli/generate) command to add new files for additional components and services, and code for new pipes, directives, and so on.
5966
Commands such as [add](cli/add) and [generate](cli/generate), which create or operate on applications and libraries, must be executed from within a workspace or project folder.
6067

61-
* See more about the [Workspace file structure](guide/file-structure).
68+
* See more about the [Workspace file structure](guide/file-structure).
6269

6370
### Workspace and project configuration
6471

6572
A single workspace configuration file, `angular.json`, is created at the top level of the workspace.
6673
This is where you can set per-project defaults for CLI command options, and specify configurations to use when the CLI builds a project for different targets.
6774

6875
The [ng config](cli/config) command lets you set and retrieve configuration values from the command line, or you can edit the `angular.json` file directly.
69-
Note that option names in the configuration file must use [camelCase](guide/glossary#case-types), while option names supplied to commands must be dash-case.
7076

71-
* See more about [Workspace Configuration](guide/workspace-config).
77+
<div class="alert is-helpful">
78+
79+
**NOTE**: <br />
80+
Option names in the configuration file must use [camelCase](guide/glossary#case-types), while option names supplied to commands must be dash-case.
81+
82+
</div>
83+
84+
* See more about [Workspace Configuration](guide/workspace-config).
7285

7386
## CLI command-language syntax
7487

7588
Command syntax is shown as follows:
7689

7790
`ng` *commandNameOrAlias* *requiredArg* [*optionalArg*] `[options]`
7891

79-
* Most commands, and some options, have aliases. Aliases are shown in the syntax statement for each command.
92+
* Most commands, and some options, have aliases.
93+
Aliases are shown in the syntax statement for each command.
8094

81-
* Option names are prefixed with a double dash (--).
82-
Option aliases are prefixed with a single dash (-).
95+
* Option names are prefixed with a double dash \(`--`\) characters.
96+
Option aliases are prefixed with a single dash \(`-`\) character.
8397
Arguments are not prefixed.
8498
For example:
85-
<code-example language="bash">
86-
ng build my-app -c production
99+
100+
<code-example format="shell" language="shell">
101+
102+
ng build my-app -c production
103+
87104
</code-example>
88105

89-
* Typically, the name of a generated artifact can be given as an argument to the command or specified with the --name option.
106+
* Typically, the name of a generated artifact can be given as an argument to the command or specified with the `--name` option.
90107

91-
* Argument and option names can be given in either
92-
[camelCase or dash-case](guide/glossary#case-types).
93-
`--myOptionName` is equivalent to `--my-option-name`.
108+
* Argument and option names can be given in either [camelCase or dash-case](guide/glossary#case-types).
109+
`--myOptionName` is equivalent to `--my-option-name`.
94110

95111
### Boolean options
96112

97113
Boolean options have two forms: `--this-option` sets the flag to `true`, `--no-this-option` sets it to `false`.
98114
If neither option is supplied, the flag remains in its default state, as listed in the reference documentation.
99115

100-
101116
### Relative paths
102117

103118
Options that specify files can be given as absolute paths, or as paths relative to the current working directory, which is generally either the workspace or project root.
104119

105120
### Schematics
106121

107-
The [ng generate](cli/generate) and [ng add](cli/add) commands take as an argument the artifact or library to be generated or added to the current project.
122+
The [ng generate](cli/generate) and [ng add](cli/add) commands take as an argument the artifact or library to be generated or added to the current project.
108123
In addition to any general options, each artifact or library defines its own options in a *schematic*.
109124
Schematic options are supplied to the command in the same format as immediate command options.
125+
126+
<!-- links -->
127+
128+
<!-- external links -->
129+
130+
<!-- end links -->
131+
132+
@reviewed 2022-02-28

‎aio/content/cli/usage-analytics-gathering.md‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,27 +20,43 @@ This ID is a string that looks like `UA-123456-12`.
2020
You can choose to use a descriptive string as the key value, or be assigned a random key when you run the CLI command.
2121
For example, the following command adds a configuration key named "tracking".
2222

23-
<code-example language="sh">
23+
<code-example format="shell" language="shell">
24+
2425
ng config --global cli.analyticsSharing.tracking UA-123456-12
26+
2527
</code-example>
2628

2729
To turn off this feature, run the following command:
2830

29-
<code-example language="sh">
31+
<code-example format="shell" language="shell">
32+
3033
ng config --global cli.analyticsSharing undefined
34+
3135
</code-example>
3236

3337
## Per user tracking
3438

3539
You can add a custom user ID to the global configuration, in order to identify unique usage of commands and flags.
3640
If that user enables CLI analytics for their own project, your analytics display tracks and labels their individual usage.
3741

38-
<code-example language="sh">
42+
<code-example format="shell" language="shell">
43+
3944
ng config --global cli.analyticsSharing.uuid SOME_USER_NAME
45+
4046
</code-example>
4147

4248
To generate a new random user ID, run the following command:
4349

44-
<code-example language="sh">
50+
<code-example format="shell" language="shell">
51+
4552
ng config --global cli.analyticsSharing.uuid ""
53+
4654
</code-example>
55+
56+
<!-- links -->
57+
58+
<!-- external links -->
59+
60+
<!-- end links -->
61+
62+
@reviewed 2022-02-28

‎aio/content/errors/NG0100.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,27 @@
44
@shortDescription Expression has changed after it was checked
55

66
@description
7+
78
Angular throws an `ExpressionChangedAfterItHasBeenCheckedError` when an expression value has been changed after change detection has completed. Angular only throws this error in development mode.
89

9-
In development mode, Angular performs an additional check after each change detection run, to ensure the bindings haven’t changed. This catches errors where the view is left in an inconsistent state. This can occur, for example, if a method or getter returns a different value each time it is called, or if a child component changes values on its parent. If either of these occur, this is a sign that change detection is not stabilized. Angular throws the error to ensure data is always reflected correctly in the view, which prevents erratic UI behavior or a possible infinite loop.
10+
In development mode, Angular performs an additional check after each change detection run, to ensure the bindings haven't changed. This catches errors where the view is left in an inconsistent state. This can occur, for example, if a method or getter returns a different value each time it is called, or if a child component changes values on its parent. If either of these occur, this is a sign that change detection is not stabilized. Angular throws the error to ensure data is always reflected correctly in the view, which prevents erratic UI behavior or a possible infinite loop.
1011

11-
This error commonly occurs when you’ve added template expressions or begun to implement lifecycle hooks like `ngAfterViewInit` or `ngOnChanges`. It is also common when dealing with loading status and asynchronous operations, or a child component changes its parent bindings.
12+
This error commonly occurs when you've added template expressions or begun to implement lifecycle hooks like `ngAfterViewInit` or `ngOnChanges`. It is also common when dealing with loading status and asynchronous operations, or a child component changes its parent bindings.
1213

1314
@debugging
14-
The [source maps](https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map) generated by the CLI are very useful when debugging. Navigate up the call stack until you find a template expression where the value displayed in the error has changed.
15+
16+
The [source maps](https://developer.mozilla.org/docs/Tools/Debugger/How_to/Use_a_source_map) generated by the CLI are very useful when debugging. Navigate up the call stack until you find a template expression where the value displayed in the error has changed.
1517

1618
Ensure that there are no changes to the bindings in the template after change detection is run. This often means refactoring to use the correct [component lifecycle hook](guide/lifecycle-hooks) for your use case. If the issue exists within `ngAfterViewInit`, the recommended solution is to use a constructor or `ngOnInit` to set initial values, or use `ngAfterContentInit` for other value bindings.
1719

1820
If you are binding to methods in the view, ensure that the invocation does not update any of the other bindings in the template.
1921

20-
Read more about which solution is right for you in ['Everything you need to know about the "ExpressionChangedAfterItHasBeenCheckedError" error'](https://indepth.dev/posts/1001/everything-you-need-to-know-about-the-expressionchangedafterithasbeencheckederror-error) and why this is useful at ['Angular Debugging "Expression has changed after it was checked": Simple Explanation (and Fix)'](https://blog.angular-university.io/angular-debugging/).
22+
Read more about which solution is right for you in ['Everything you need to know about the "ExpressionChangedAfterItHasBeenCheckedError" error'](https://indepth.dev/posts/1001/everything-you-need-to-know-about-the-expressionchangedafterithasbeencheckederror-error) and why this is useful at ['Angular Debugging "Expression has changed after it was checked": Simple Explanation (and Fix)'](https://blog.angular-university.io/angular-debugging).
23+
24+
<!-- links -->
25+
26+
<!-- external links -->
27+
28+
<!-- end links -->
29+
30+
@reviewed 2022-02-28

‎aio/content/errors/NG0200.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@
77
A cyclic dependency exists when a [dependency of a service](guide/hierarchical-dependency-injection) directly or indirectly depends on the service itself. For example, if `UserService` depends on `EmployeeService`, which also depends on `UserService`. Angular will have to instantiate `EmployeeService` to create `UserService`, which depends on `UserService`, itself.
88

99
@debugging
10-
Use the call stack to determine where the cyclical dependency exists. You will be able to see if any child dependencies rely on the original file by [mapping out](guide/dependency-injection-in-action) the component, module, or service’s dependencies and identify the loop causing the problem.
10+
Use the call stack to determine where the cyclical dependency exists. You will be able to see if any child dependencies rely on the original file by [mapping out](guide/dependency-injection-in-action) the component, module, or service's dependencies and identify the loop causing the problem.
1111

12-
Break this loop (or circle) of dependency to resolve this error. This most commonly means removing or refactoring the dependencies to not be reliant on one another.
12+
Break this loop \(or circle\) of dependency to resolve this error. This most commonly means removing or refactoring the dependencies to not be reliant on one another.
13+
14+
<!-- links -->
15+
16+
<!-- external links -->
17+
18+
<!-- end links -->
19+
20+
@reviewed 2022-02-28

‎aio/content/errors/NG0201.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,16 @@ To fix the error ensure that your service is registered in the list of providers
1515

1616
The most common solution is to add a provider in `@Injectable` using `providedIn`:
1717

18-
```typescript
19-
@Injectable({ providedIn: 'app' })
20-
```
18+
<code-example format="typescript" language="typescript">
19+
20+
&commat;Injectable({ providedIn: 'app' })
21+
22+
</code-example>
23+
24+
<!-- links -->
25+
26+
<!-- external links -->
27+
28+
<!-- end links -->
29+
30+
@reviewed 2022-02-28

‎aio/content/errors/NG0300.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,25 @@
77
Two or more components use the same [element selector](guide/component-overview#specifying-a-components-css-selector). Because there can only be a single component associated with an element, selectors must be unique strings to prevent ambiguity for Angular.
88

99
@debugging
10-
Use the element name from the error message to search for places where you’re using the same [selector declaration](guide/architecture-components) in your codebase:
10+
Use the element name from the error message to search for places where you're using the same [selector declaration](guide/architecture-components) in your codebase:
1111

12-
```typescript
13-
@Component({
12+
<code-example format="typescript" language="typescript">
13+
14+
&commat;Component({
1415
selector: 'YOUR_STRING',
15-
...
16+
&hellip;
1617
})
17-
```
18+
19+
</code-example>
1820

1921
Ensure that each component has a unique CSS selector. This will guarantee that Angular renders the component you expect.
2022

21-
If you’re having trouble finding multiple components with this selector tag name, check for components from imported component libraries, such as Angular Material. Make sure you're following the [best practices](guide/styleguide#component-selectors) for your selectors to prevent collisions.
23+
If you're having trouble finding multiple components with this selector tag name, check for components from imported component libraries, such as Angular Material. Make sure you're following the [best practices](guide/styleguide#component-selectors) for your selectors to prevent collisions.
24+
25+
<!-- links -->
26+
27+
<!-- external links -->
28+
29+
<!-- end links -->
30+
31+
@reviewed 2022-02-28

‎aio/content/errors/NG0301.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
@shortDescription Export not found!
55

66
@description
7-
Angular can’t find a directive with `{{ PLACEHOLDER }}` export name. The export name is specified in the `exportAs` property of the directive decorator. This is common when using FormsModule or Material modules in templates, and you’ve forgotten to [import the corresponding modules](guide/sharing-ngmodules).
7+
Angular can't find a directive with `{{ PLACEHOLDER }}` export name. The export name is specified in the `exportAs` property of the directive decorator. This is common when using FormsModule or Material modules in templates, and you've forgotten to [import the corresponding modules](guide/sharing-ngmodules).
88

99
<div class="alert is-helpful">
1010

@@ -17,16 +17,24 @@ Use the export name to trace the templates or modules using this export.
1717

1818
Ensure that all dependencies are [properly imported and declared in your NgModules](guide/sharing-ngmodules). For example, if the export not found is `ngForm`, we need to import `FormsModule` and declare it in the list of imports in `*.module.ts` to resolve the error.
1919

20-
```typescript
21-
import { FormsModule } from '@angular/forms';
20+
<code-example format="typescript" language="typescript">
2221

23-
@NgModule({
24-
...
22+
import { FormsModule } from '&commat;angular/forms';
23+
24+
&commat;NgModule({
25+
&hellip;
2526
imports: [
2627
FormsModule,
27-
…
28-
```
28+
&hellip;
29+
30+
</code-example>
2931

3032
If you recently added an import, you may need to restart your server to see these changes.
3133

34+
<!-- links -->
35+
36+
<!-- external links -->
37+
38+
<!-- end links -->
3239

40+
@reviewed 2022-02-28

‎aio/content/errors/NG0302.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,24 @@
44
@shortDescription Pipe not found!
55

66
@description
7-
Angular can't find a pipe with this name.
8-
The pipe referenced in the template has not been named or declared properly.
7+
Angular can't find a pipe with this name.
8+
The pipe referenced in the template has not been named or declared properly.
99
A [pipe](guide/pipes) must be either declared or imported in the `NgModule` where it is used, and the name used in a template must match the name defined in the pipe decorator.
1010

1111
@debugging
1212
Use the pipe name to trace the templates or modules where this pipe is declared and used.
1313

1414
To resolve this error, ensure that:
15-
- A local custom pipe is uniquely named in the pipe's decorator, and declared in the `NgModule`, or
16-
- A pipe from another `NgModule` is added to the imports of the `NgModule` where it is used.
15+
16+
* A local custom pipe is uniquely named in the pipe's decorator, and declared in the `NgModule`, or
17+
* A pipe from another `NgModule` is added to the imports of the `NgModule` where it is used
1718

1819
If you recently added an import or declaration, you may need to restart your server to see these changes.
20+
21+
<!-- links -->
22+
23+
<!-- external links -->
24+
25+
<!-- end links -->
26+
27+
@reviewed 2022-02-28

0 commit comments

Comments
 (0)