docs: add asset config details

aio/content/guide/workspace-config.md

@@ -1,18 +1,18 @@
 # Angular Workspace Configuration
 
-A file named `angular.json` at the root level of an Angular [workspace](guide/glossary#workspace) provides workspace-wide and project-specific configuration defaults for build and development tools provided by the Angular CLI. 
-Path values given in the configuration are relative to the root workspace folder. 
+A file named `angular.json` at the root level of an Angular [workspace](guide/glossary#workspace) provides workspace-wide and project-specific configuration defaults for build and development tools provided by the Angular CLI.
+Path values given in the configuration are relative to the root workspace folder.
 
 ## Overall JSON structure
 
-At the top level of `angular.json`, a few properties configure the workspace, and a `projects` section contains the remaining per-project configuration options. 
+At the top level of `angular.json`, a few properties configure the workspace, and a `projects` section contains the remaining per-project configuration options.
 
 * `version`: The configuration-file version.
 * `newProjectRoot`: Path where new projects are created. Absolute or relative to the workspace folder.
 * `defaultProject`: Default project name to use in commands, where not provided as an argument. When you use `ng new` to create a new app in a new workspace, that app is the default project for the workspace until you change it here.
-* `projects` : Contains a subsection for each project (library, app, e2e test app) in the workspace, with the per-project configuration options. 
+* `projects` : Contains a subsection for each project (library, app, e2e test app) in the workspace, with the per-project configuration options.
 
-The initial app that you create with `ng new app_name` is listed under "projects", along with its corresponding end-to-end test app: 
+The initial app that you create with `ng new app_name` is listed under "projects", along with its corresponding end-to-end test app:
 
 <code-example format="." language="none" linenums="false">
 projects
@@ -23,11 +23,11 @@ projects
 </code-example>
 
 Each additional app that you create with `ng generate application` has a corresponding end-to-end test project, with its own configuration section.
-When you create a library project with `ng generate library`, the library project is also added to the `projects` section. 
+When you create a library project with `ng generate library`, the library project is also added to the `projects` section.
 
 <div class="alert is-helpful">
 
-  Note that the `projects` section of the configuration file does not correspond exactly to the workspace file structure. 
+  Note that the `projects` section of the configuration file does not correspond exactly to the workspace file structure.
   * The initial app created by `ng new` is at the top level of the workspace file structure, along with its e2e app.
   * Additional apps, e2e apps, and libraries go into a `projects` folder in the workspace.
 
@@ -63,7 +63,7 @@ The following top-level configuration properties are available for each project,
 
 Architect is the tool that the CLI uses to perform complex tasks such as compilation and test running, according to provided configurations. The `architect` section contains a set of Architect *targets*. Many of the targets correspond to the CLI commands that run them. Some additional predefined targets can be run using the `ng run` command, and you can define your own targets.
 
-Each target object specifies the `builder` for that target, which is the npm package for the tool that Architect runs. In addition, each target has an `options` section that configure default options for the target, and a `configurations` section that names and specifies alternative configurations for the target. See the example in [Build target](#build-target) below. 
+Each target object specifies the `builder` for that target, which is the npm package for the tool that Architect runs. In addition, each target has an `options` section that configure default options for the target, and a `configurations` section that names and specifies alternative configurations for the target. See the example in [Build target](#build-target) below.
 
 <code-example format="." language="json" linenums="false">
       "architect": {
@@ -90,11 +90,11 @@ Each target object specifies the `builder` for that target, which is the npm pac
 
 * The `architect/extract-i18n` section configures defaults for options of the `ng-xi18n` tool used by the `ng xi18n` command, which extracts marked message strings from source code and outputs translation files.
 
-* The `architect/server` section configures defaults for creating a Universal app with server-side rendering, using the `ng run <project>:server` command. 
+* The `architect/server` section configures defaults for creating a Universal app with server-side rendering, using the `ng run <project>:server` command.
 
 * The `architect/app-shell` section configures defaults for creating an app shell for a progressive web app (PWA), using the `ng run <project>:app-shell` command.
 
-In general, the options for which you can configure defaults correspond to the command options listed in the [CLI reference page](cli) for each command. 
+In general, the options for which you can configure defaults correspond to the command options listed in the [CLI reference page](cli) for each command.
 Note that all options in the configuration file must use [camelCase](guide/glossary#case-conventions), rather than dash-case.
 
 {@a build-target}
@@ -113,23 +113,73 @@ The `architect/build` section configures defaults for options of the `ng build`
 
 ### Alternate build configurations
 
-By default, a `production` configuration is defined, and the `ng build` command has `--prod` option that builds using this configuration. The `production` configuration sets defaults that optimize the app in a number of ways, such bundling files, minimizing excess whitespace, removing comments and dead code, and rewriting code to use short, cryptic names ("minification"). 
+By default, a `production` configuration is defined, and the `ng build` command has `--prod` option that builds using this configuration. The `production` configuration sets defaults that optimize the app in a number of ways, such bundling files, minimizing excess whitespace, removing comments and dead code, and rewriting code to use short, cryptic names ("minification").
 
-You can define and name additional alternate configurations (such as `stage`, for instance) appropriate to your development process. Some examples of different build configurations are `stable`, `archive` and `next` used by AIO itself, and the individual locale-specific configurations required for building localized versions of an app. For details, see [Internationalization (i18n)](guide/i18n#merge-aot). 
+You can define and name additional alternate configurations (such as `stage`, for instance) appropriate to your development process. Some examples of different build configurations are `stable`, `archive` and `next` used by AIO itself, and the individual locale-specific configurations required for building localized versions of an app. For details, see [Internationalization (i18n)](guide/i18n#merge-aot).
 
 {@a build-props}
 
 ### Additional build and test options
 
-The configurable options for a default or targeted build generally correspond to the options available for the [`ng build`](cli/build), [`ng serve`](cli/serve), and [`ng test`](cli/test) commands. For details of those options and their possible values, see the [CLI Reference](cli). 
+The configurable options for a default or targeted build generally correspond to the options available for the [`ng build`](cli/build), [`ng serve`](cli/serve), and [`ng test`](cli/test) commands. For details of those options and their possible values, see the [CLI Reference](cli).
 
 Some additional options (listed below) can only be set through the configuration file, either by direct editing or with the [`ng config`](cli/config) command.
 
 | OPTIONS PROPERTIES | DESCRIPTION |
 | :------------------------- | :---------------------------- |
 | `fileReplacements`         | An object containing files and their compile-time replacements. |
 | `stylePreprocessorOptions` | An object containing option-value pairs to pass to style preprocessors. |
-| `assets`                   | An object containing paths to static assets to add to the global context of the project. The default paths point to the project's icon file and its `assets` folder. |
+| `assets`                   | An object containing paths to static assets to add to the global context of the project. The default paths point to the project's icon file and its `assets` folder.  See more below. |
 | `styles`                   | An object containing style files to add to the global context of the project. Angular CLI supports CSS imports and all major CSS preprocessors: [sass/scss](http://sass-lang.com/), [less](http://lesscss.org/), and [stylus](http://stylus-lang.com/). |
 | `scripts`                  | An object containing JavaScript script files to add to the global context of the project. The scripts are loaded exactly as if you had added them in a `<script>` tag inside `index.html`. |
 | `budgets`                  | Default size-budget type and threshholds for all or parts of your app. You can configure the builder to report a warning or an error when the output reaches or exceeds a threshold size. See [Configure size budgets](guide/build#configure-size-budgets). (Not available in `test` section.) |
+
+## Project asset configuration
+
+Each `build` target configuration can include as `assets` array that lists files or folders you want to copy as-is when building your project.
+By default, the `src/assets/` folder and `src/favicon.ico` are copied over.
+
+<code-example format="." language="json" linenums="false">
+"assets": [
+  "src/assets",
+  "src/favicon.ico"
+]
+</code-example>
+
+To exclude an asset, you can remove it from the assets configuration.
+
+You can further configure assets to be copied by specifying assets as objects, rather than as simple paths relative to the workspace root.
+A asset specification object can have the following fields.
+
+* `glob`:  A node-glob using `input` as base directory.
+* `input`: A path relative to the workspace root.
+* `output`: A path relative to `outDir` (default is `dist/`*project-name*). Because of the security implications, the CLI never writes files outside of the project output path.
+* `ignore`: A list of globs to exclude.
+
+For example, the default asset paths can be represented in more detail using the following objects.
+
+<code-example format="." language="json" linenums="false">
+"assets": [
+  { "glob": "**/*", "input": "src/assets/", "output": "/assets/" },
+  { "glob": "favicon.ico", "input": "src/", "output": "/" },
+]
+</code-example>
+
+You can use this extended configuration to copy assets from outside your project.
+For example, the following configuration copies assets from a node package:
+
+<code-example format="." language="json" linenums="false">
+"assets": [
+ { "glob": "**/*", "input": "./node_modules/some-package/images", "output": "/some-package/" },
+]
+</code-example>
+
+The contents of `node_modules/some-package/images/` will be available in `dist/some-package/`.
+
+The following example uses the `ignore` field to exclude certain files in the assets folder from being copied into the build:
+
+<code-example format="." language="json" linenums="false">
+"assets": [
+ { "glob": "**/*", "input": "src/assets/", "ignore": ["**/*.svg"], "output": "/assets/" },
+]
+</code-example>