docs: fix code example formats (#31115)

PR Close #31115
This commit is contained in:
Judy Bogart 2019-06-19 11:37:41 -07:00 committed by Kara Erickson
parent f4fe1f65be
commit 9177ffaf58
1 changed files with 49 additions and 3 deletions

View File

@ -30,7 +30,9 @@ You will need two terminals to get the live-reload experience.
* On the first terminal, run the [`ng build` command](cli/build) in *watch* mode to compile the application to the `dist` folder. * On the first terminal, run the [`ng build` command](cli/build) in *watch* mode to compile the application to the `dist` folder.
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
ng build --watch ng build --watch
</code-example> </code-example>
Like the `ng serve` command, this regenerates output files when source files change. Like the `ng serve` command, this regenerates output files when source files change.
@ -38,7 +40,9 @@ You will need two terminals to get the live-reload experience.
* On the second terminal, install a web server (such as [lite-server](https://github.com/johnpapa/lite-server)), and run it against the output folder. For example: * On the second terminal, install a web server (such as [lite-server](https://github.com/johnpapa/lite-server)), and run it against the output folder. For example:
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
lite-server --baseDir="dist" lite-server --baseDir="dist"
</code-example> </code-example>
The server will automatically reload your browser when new files are output. The server will automatically reload your browser when new files are output.
@ -56,7 +60,9 @@ For the simplest deployment, create a production build and copy the output direc
1. Start with the production build: 1. Start with the production build:
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
ng build --prod ng build --prod
</code-example> </code-example>
@ -78,7 +84,9 @@ Make a note of the user name and project name in GitHub.
1. Build your project using Github project name, with the Angular CLI command [`ng build`](cli/build) and the options shown here: 1. Build your project using Github project name, with the Angular CLI command [`ng build`](cli/build) and the options shown here:
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
ng build --prod --output-path docs --base-href /<project_name>/
ng build --prod --output-path docs --base-href /&lt;project_name&gt;/
</code-example> </code-example>
1. When the build is complete, make a copy of `docs/index.html` and name it `docs/404.html`. 1. When the build is complete, make a copy of `docs/index.html` and name it `docs/404.html`.
@ -144,6 +152,7 @@ The list is by no means exhaustive, but should provide you with a good starting
(https://ngmilk.rocks/2015/03/09/angularjs-html5-mode-or-pretty-urls-on-apache-using-htaccess/): (https://ngmilk.rocks/2015/03/09/angularjs-html5-mode-or-pretty-urls-on-apache-using-htaccess/):
<code-example format="."> <code-example format=".">
RewriteEngine On RewriteEngine On
&#35 If an existing asset or directory is requested go to it as it is &#35 If an existing asset or directory is requested go to it as it is
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR] RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
@ -152,6 +161,7 @@ The list is by no means exhaustive, but should provide you with a good starting
&#35 If the requested resource doesn't exist, use index.html &#35 If the requested resource doesn't exist, use index.html
RewriteRule ^ /index.html RewriteRule ^ /index.html
</code-example> </code-example>
@ -160,7 +170,9 @@ The list is by no means exhaustive, but should provide you with a good starting
modified to serve `index.html`: modified to serve `index.html`:
<code-example format="."> <code-example format=".">
try_files $uri $uri/ /index.html; try_files $uri $uri/ /index.html;
</code-example> </code-example>
@ -168,6 +180,7 @@ modified to serve `index.html`:
[here](http://stackoverflow.com/a/26152011/2116927): [here](http://stackoverflow.com/a/26152011/2116927):
<code-example format='.' linenums="false"> <code-example format='.' linenums="false">
&lt;system.webServer&gt; &lt;system.webServer&gt;
&lt;rewrite&gt; &lt;rewrite&gt;
&lt;rules&gt; &lt;rules&gt;
@ -182,6 +195,7 @@ modified to serve `index.html`:
&lt;/rules&gt; &lt;/rules&gt;
&lt;/rewrite&gt; &lt;/rewrite&gt;
&lt;/system.webServer&gt; &lt;/system.webServer&gt;
</code-example> </code-example>
@ -200,10 +214,12 @@ and to
[rewrite rule](https://firebase.google.com/docs/hosting/url-redirects-rewrites#section-rewrites). [rewrite rule](https://firebase.google.com/docs/hosting/url-redirects-rewrites#section-rewrites).
<code-example format="."> <code-example format=".">
"rewrites": [ { "rewrites": [ {
"source": "**", "source": "**",
"destination": "/index.html" "destination": "/index.html"
} ] } ]
</code-example> </code-example>
{@a cors} {@a cors}
@ -245,9 +261,11 @@ See [`ng build`](cli/build) for more about CLI build options and what they do.
In addition to build optimizations, Angular also has a runtime production mode. Angular apps run in development mode by default, as you can see by the following message on the browser console: In addition to build optimizations, Angular also has a runtime production mode. Angular apps run in development mode by default, as you can see by the following message on the browser console:
``` <code-example format="nocode">
Angular is running in the development mode. Call enableProdMode() to enable the production mode. Angular is running in the development mode. Call enableProdMode() to enable the production mode.
```
</code-example>
Switching to _production mode_ makes it run faster by disabling development specific checks such as the dual change detection cycles. Switching to _production mode_ makes it run faster by disabling development specific checks such as the dual change detection cycles.
@ -311,26 +329,34 @@ tool is a great way to inspect the generated JavaScript bundles after a producti
Install `source-map-explorer`: Install `source-map-explorer`:
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
npm install source-map-explorer --save-dev npm install source-map-explorer --save-dev
</code-example> </code-example>
Build your app for production _including the source maps_ Build your app for production _including the source maps_
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
ng build --prod --source-map ng build --prod --source-map
</code-example> </code-example>
List the generated bundles in the `dist/` folder. List the generated bundles in the `dist/` folder.
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
ls dist/*.bundle.js ls dist/*.bundle.js
</code-example> </code-example>
Run the explorer to generate a graphical representation of one of the bundles. Run the explorer to generate a graphical representation of one of the bundles.
The following example displays the graph for the _main_ bundle. The following example displays the graph for the _main_ bundle.
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
node_modules/.bin/source-map-explorer dist/main.*.bundle.js node_modules/.bin/source-map-explorer dist/main.*.bundle.js
</code-example> </code-example>
The `source-map-explorer` analyzes the source map generated with the bundle and draws a map of all dependencies, The `source-map-explorer` analyzes the source map generated with the bundle and draws a map of all dependencies,
@ -419,6 +445,7 @@ When you create a production build using [`ng build --prod`](cli/build), the CLI
The `index.html` file is also modified during the build process to include script tags that enable differential loading. See the sample output below from the `index.html` file produced during a build using `ng build`. The `index.html` file is also modified during the build process to include script tags that enable differential loading. See the sample output below from the `index.html` file produced during a build using `ng build`.
<code-example language="html" format="." linenums="false"> <code-example language="html" format="." linenums="false">
<!-- ... --> <!-- ... -->
<body> <body>
<app-root></app-root> <app-root></app-root>
@ -434,6 +461,7 @@ The `index.html` file is also modified during the build process to include scrip
<script src="main-es5.js" nomodule></script> <script src="main-es5.js" nomodule></script>
</body> </body>
<!-- ... --> <!-- ... -->
</code-example> </code-example>
Each script tag has a `type="module"` or `nomodule` attribute. Browsers with native support for ES modules only load the scripts with the `module` type attribute and ignore scripts with the `nomodule` attribute. Legacy browsers only load the scripts with the `nomodule` attribute, and ignore the script tags with the `module` type that load ES modules. Each script tag has a `type="module"` or `nomodule` attribute. Browsers with native support for ES modules only load the scripts with the `module` type attribute and ignore scripts with the `nomodule` attribute. Legacy browsers only load the scripts with the `nomodule` attribute, and ignore the script tags with the `module` type that load ES modules.
@ -464,6 +492,7 @@ not IE 9-11 # For IE 9-11 support, remove 'not'.
The `tsconfig.json` looks like this: The `tsconfig.json` looks like this:
<code-example language="json" format="." linenums="false"> <code-example language="json" format="." linenums="false">
{ {
"compileOnSave": false, "compileOnSave": false,
"compilerOptions": { "compilerOptions": {
@ -486,6 +515,7 @@ The `tsconfig.json` looks like this:
] ]
} }
} }
</code-example> </code-example>
By default, legacy browsers such as IE 9-11 are ignored, and the compilation target is ES2015. As a result, this produces two builds, and differential loading is enabled. If you ignore browsers without ES2015 support, a single build is produced. To see the build result for differential loading based on different configurations, refer to the table below. By default, legacy browsers such as IE 9-11 are ignored, and the compilation target is ES2015. As a result, this produces two builds, and differential loading is enabled. If you ignore browsers without ES2015 support, a single build is produced. To see the build result for differential loading based on different configurations, refer to the table below.
@ -533,17 +563,20 @@ To maintain the benefits of differential loading, however, a better option is to
To do this for `ng serve`, create a new file, `tsconfig-es5.app.json` next to `tsconfig.app.json` with the following content. To do this for `ng serve`, create a new file, `tsconfig-es5.app.json` next to `tsconfig.app.json` with the following content.
<code-example language="json" format="." linenums="false"> <code-example language="json" format="." linenums="false">
{ {
"extends": "./tsconfig.app.json", "extends": "./tsconfig.app.json",
"compilerOptions": { "compilerOptions": {
"target": "es5" "target": "es5"
} }
} }
</code-example> </code-example>
In `angular.json` add two new configuration sections under the `build` and `serve` targets to point to the new TypeScript configuration. In `angular.json` add two new configuration sections under the `build` and `serve` targets to point to the new TypeScript configuration.
<code-example language="json" format="." linenums="false"> <code-example language="json" format="." linenums="false">
"build": { "build": {
"builder": "@angular-devkit/build-angular:browser", "builder": "@angular-devkit/build-angular:browser",
"options": { "options": {
@ -572,12 +605,15 @@ In `angular.json` add two new configuration sections under the `build` and `serv
} }
} }
}, },
</code-example> </code-example>
You can then run the serve with this configuration. You can then run the serve with this configuration.
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
ng serve --configuration es5 ng serve --configuration es5
</code-example> </code-example>
{@ differential-test} {@ differential-test}
@ -587,15 +623,18 @@ ng serve --configuration es5
Create a new file, `tsconfig-es5.spec.json` next to `tsconfig.spec.json` with the following content. Create a new file, `tsconfig-es5.spec.json` next to `tsconfig.spec.json` with the following content.
<code-example language="json" format="." linenums="false"> <code-example language="json" format="." linenums="false">
{ {
"extends": "./tsconfig.spec.json", "extends": "./tsconfig.spec.json",
"compilerOptions": { "compilerOptions": {
"target": "es5" "target": "es5"
} }
} }
</code-example> </code-example>
<code-example language="json" format="." linenums="false"> <code-example language="json" format="." linenums="false">
"test": { "test": {
"builder": "@angular-devkit/build-angular:karma", "builder": "@angular-devkit/build-angular:karma",
"options": { "options": {
@ -607,12 +646,15 @@ Create a new file, `tsconfig-es5.spec.json` next to `tsconfig.spec.json` with th
} }
} }
}, },
</code-example </code-example
You can then run the tests with this configuration You can then run the tests with this configuration
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
ng test --configuration es5 ng test --configuration es5
</code-example> </code-example>
### Configuring the e2e command ### Configuring the e2e command
@ -620,6 +662,7 @@ ng test --configuration es5
Create an ES5 serve configuration as explained above (link to the above serve section), and configuration an ES5 configuration for the E2E target. Create an ES5 serve configuration as explained above (link to the above serve section), and configuration an ES5 configuration for the E2E target.
<code-example language="json" format="." linenums="false"> <code-example language="json" format="." linenums="false">
"test": { "test": {
"builder": "@angular-devkit/build-angular:protractor", "builder": "@angular-devkit/build-angular:protractor",
"options": { "options": {
@ -634,10 +677,13 @@ Create an ES5 serve configuration as explained above (link to the above serve se
} }
} }
}, },
</code-example> </code-example>
You can then run the e2e's with this configuration You can then run the e2e's with this configuration
<code-example language="none" class="code-shell"> <code-example language="none" class="code-shell">
ng e2e --configuration es5 ng e2e --configuration es5
</code-example> </code-example>