docs(core): enhance markdown markup (#10969)

docs/shared/angular-tutorial/01-create-application.md

@@ -7,7 +7,9 @@ width="100%" /%}
 
 In this tutorial you use Nx to build a full-stack application out of common libraries using modern technologies like Cypress and Nest.
 
-> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/getting-started/nx-core).
+{% callout type="note" title="Plugins for a rich developer experience" %}
+In this tutorial, we use several Nx plugins to provide a rich developer experience that do most of the work for you. **All the plugins are optional.** [Read about using Nx Core without plugins](/getting-started/nx-core).
+{% /callout %}
 
 ## Create a new workspace
 
@@ -106,27 +108,41 @@ Depending on how your dev env is set up, the command above might result in `Comm
 
 To fix it, you can either install the `nx` cli globally by running:
 
-```bash
+{% tabs %}
-npm install -g nx
+{% tab label="yarn" %}
-```
-
-or
 
 ```bash
 yarn global add nx
 ```
 
+{% /tab %}
+{% tab label="npm" %}
+
+```bash
+npm install -g nx
+```
+
+{% /tab %}
+{% /tabs %}
+
 Alternatively, you can run the local installation of Nx by prepending every command with `npx`:
 
+{% tabs %}
+{% tab label="yarn" %}
+
+```bash
+yarn nx serve todos
+```
+
+{% /tab %}
+{% tab label="npm" %}
+
 ```bash
 npx nx serve todos
 ```
 
-or
+{% /tab %}
-
+{% /tabs %}
-```bash
-yarn nx serve todos
-```
 
 ## Note on `nx serve` and `ng serve`
 

docs/shared/angular-tutorial/05-add-node-app.md

@@ -44,17 +44,26 @@ Nx is an extensible framework with plugins for many modern tools and frameworks.
 
 **Add the dependency:**
 
-```bash
+{% tabs %}
-npm install --save-dev @nrwl/nest
+{% tab label="yarn" %}
-```
-
-or
 
 ```bash
 yarn add --dev @nrwl/nest
 ```
 
-> `@nrwl/nest` also added `@nrwl/node`. Run `nx list @nrwl/nest` and `nx list @nrwl/node` to see what those plugins provide.
+{% /tab %}
+{% tab label="npm" %}
+
+```bash
+npm install --save-dev @nrwl/nest
+```
+
+{% /tab %}
+{% /tabs %}
+
+{% callout type="check" title="List plugins" %}
+When installing `@nrwl/nest`, it also automatically added `@nrwl/node` for you. Run `npx nx list @nrwl/nest` and `npx nx list @nrwl/node` to see what those plugins provide.
+{% /callout %}
 
 ## Create a NestJS application
 
@@ -103,9 +112,11 @@ The `apps` directory is where Nx places anything you can run: frontend applicati
 
 You can run:
 
-- `npx nx serve api` to serve the application
+| Command          | Description           |
-- `npx nx build api` to build the application
+| ---------------- | --------------------- |
-- `npx nx test api` to test the application
+| npx nx serve api | serve the application |
+| npx nx build api | build the application |
+| npx nx test api  | test the application  |
 
 **Open `apps/api/src/app/app.module.ts`.**
 

docs/shared/angular-tutorial/10-computation-caching.md

@@ -58,7 +58,9 @@ Build at: 2022-01-21T20:36:14.528Z - Hash: 795c96ce5e48a766 - Time: 11596ms
 
 Based on the state of the source code and the environment, Nx was able to figure out that it had already run this exact command. Nx found the artifact in the local cache and replayed the output and restored the necessary files.
 
-> Caching only works with the Nx CLI. Running `ng build todos` runs the command every single time.
+{% callout type="warning" title="Caching is a feature of Nx CLI" %}
+Caching only works with the Nx CLI. Running `ng build todos` runs the command every single time.
+{% /callout %}
 
 ## Building multiple projects
 
@@ -76,7 +78,9 @@ Nx read the output from the cache instead of running the command for 1 out of 2
 
 Nx built `api` and retrieved `todos` from its computation cache. Read more about the cache here [here](/using-nx/caching).
 
-> Add --parallel to any command, and Nx does most of the work in parallel.
+{% callout type="check" title="Go faster" %}
+Add --parallel to any command, and Nx does most of the work in parallel.
+{% /callout %}
 
 ## What's Next
 

docs/shared/configuration/packagejson.md

@@ -309,8 +309,9 @@ Another target default you can configure is `outputs`:
 }
 ```
 
-> Previous versions of Nx (before 14.3.4) supported `targetDependencies` to configure dependencies in `nx.json`. `targetDefaults` is the
+{% callout type="warning" title="Nx < 14.3.4" %}
-> same mechanism but generalized to support other properties.
+Previous versions of Nx (before 14.3.4) supported `targetDependencies` to configure dependencies in `nx.json`. `targetDefaults` is the same mechanism but generalized to support other properties.
+{% /callout %}
 
 ### CLI Options
 
@@ -351,19 +352,16 @@ this `nx run-many --target=build --all --runner=another`.
 Tasks runners can accept different options. The following are the options supported
 by `"nx/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
 
-- `cacheableOperations` defines the list of targets/operations that are cached by Nx.
+| Property                | Descrtipion                                                                                                                                                                                                                                                                                                                                   |
-- `parallel` defines the max number of targets ran in parallel (in older versions of Nx you had to
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-  pass `--parallel --maxParallel=3` instead of `--parallel=3`).
+| cacheableOperations     | defines the list of targets/operations that are cached by Nx                                                                                                                                                                                                                                                                                  |
-- `captureStderr` defines whether the cache captures stderr or just stdout.
+| parallel                | defines the max number of targets ran in parallel (in older versions of Nx you had to pass `--parallel --maxParallel=3` instead of `--parallel=3`)                                                                                                                                                                                            |
-- `skipNxCache` defines whether the Nx Cache should be skipped. Defaults to `false`.
+| captureStderr           | defines whether the cache captures stderr or just stdout                                                                                                                                                                                                                                                                                      |
-- `cacheDirectory` defines where the local cache is stored, which is `node_modules/.cache/nx` by default.
+| skipNxCache             | defines whether the Nx Cache should be skipped (defaults to `false`)                                                                                                                                                                                                                                                                          |
-- `encryptionKey` (when using `"@nrwl/nx-cloud"` only) defines an encryption key to support end-to-end encryption of
+| cacheDirectory          | defines where the local cache is stored (defaults to `node_modules/.cache/nx`)                                                                                                                                                                                                                                                                |
-  your cloud cache. You may also provide an environment variable with the key `NX_CLOUD_ENCRYPTION_KEY` that contains an
+| encryptionKey           | (when using `"@nrwl/nx-cloud"` only) defines an encryption key to support end-to-end encryption of your cloud cache. You may also provide an environment variable with the key `NX_CLOUD_ENCRYPTION_KEY` that contains an encryption key as its value. The Nx Cloud task runner normalizes the key length, so any length of key is acceptable |
-  encryption key as its value. The Nx Cloud task runner normalizes the key length, so any length of key is acceptable.
+| runtimeCacheInputs      | defines the list of commands that are run by the runner to include into the computation hash value                                                                                                                                                                                                                                            |
-- `runtimeCacheInputs` defines the list of commands that are run by the runner to include into the computation hash
+| selectivelyHashTsConfig | only hash the path mapping of the active project in the `tsconfig.base.json` (e.g., adding/removing projects doesn't affect the hash of existing projects) (defaults to `false`)                                                                                                                                                              |
-  value.
-- `selectivelyHashTsConfig` only hash the path mapping of the active project in the `tsconfig.base.json` (e.g.,
-  adding/removing projects doesn't affect the hash of existing projects). Defaults to `false`
 
 `runtimeCacheInputs` are set as follows:
 

docs/shared/configuration/projectjson.md

@@ -7,7 +7,9 @@ Projects can be configured in `package.json` (if you use npm scripts and not Nx
 use Nx executors). Both `package.json` and `project.json` files are located in each project's folder. Nx merges the two
 files to get each project's configuration. This guide covers the `project.json` case.
 
-> Angular developers can also configure projects in angular.json. Read [this guide](/getting-started/nx-and-angular#angularjson) for more information.
+{% callout type="note" title="Using Angular?" %}
+Angular developers can also configure projects in angular.json. [Read this guide for more information](/getting-started/nx-and-angular#angularjson).
+{% /callout %}
 
 ## Project Configuration
 
@@ -426,19 +428,16 @@ named "default" is used by default. Specify a different one like this `nx run-ma
 Tasks runners can accept different options. The following are the options supported
 by `"nx/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
 
-- `cacheableOperations` defines the list of targets/operations that are cached by Nx.
+| Property                | Descrtipion                                                                                                                                                                                                                                                                                                                                   |
-- `parallel` defines the max number of targets ran in parallel (in older versions of Nx you had to
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-  pass `--parallel --maxParallel=3` instead of `--parallel=3`).
+| cacheableOperations     | defines the list of targets/operations that are cached by Nx                                                                                                                                                                                                                                                                                  |
-- `captureStderr` defines whether the cache captures stderr or just stdout.
+| parallel                | defines the max number of targets ran in parallel (in older versions of Nx you had to pass `--parallel --maxParallel=3` instead of `--parallel=3`)                                                                                                                                                                                            |
-- `skipNxCache` defines whether the Nx Cache should be skipped. Defaults to `false`.
+| captureStderr           | defines whether the cache captures stderr or just stdout                                                                                                                                                                                                                                                                                      |
-- `cacheDirectory` defines where the local cache is stored, which is `node_modules/.cache/nx` by default.
+| skipNxCache             | defines whether the Nx Cache should be skipped (defaults to `false`)                                                                                                                                                                                                                                                                          |
-- `encryptionKey` (when using `"@nrwl/nx-cloud"` only) defines an encryption key to support end-to-end encryption of
+| cacheDirectory          | defines where the local cache is stored (defaults to `node_modules/.cache/nx`)                                                                                                                                                                                                                                                                |
-  your cloud cache. You may also provide an environment variable with the key `NX_CLOUD_ENCRYPTION_KEY` that contains an
+| encryptionKey           | (when using `"@nrwl/nx-cloud"` only) defines an encryption key to support end-to-end encryption of your cloud cache. You may also provide an environment variable with the key `NX_CLOUD_ENCRYPTION_KEY` that contains an encryption key as its value. The Nx Cloud task runner normalizes the key length, so any length of key is acceptable |
-  encryption key as its value. The Nx Cloud task runner normalizes the key length, so any length of key is acceptable.
+| runtimeCacheInputs      | defines the list of commands that are run by the runner to include into the computation hash value                                                                                                                                                                                                                                            |
-- `runtimeCacheInputs` defines the list of commands that are run by the runner to include into the computation hash
+| selectivelyHashTsConfig | only hash the path mapping of the active project in the `tsconfig.base.json` (e.g., adding/removing projects doesn't affect the hash of existing projects) (defaults to `false`)                                                                                                                                                              |
-  value.
-- `selectivelyHashTsConfig` only hash the path mapping of the active project in the `tsconfig.base.json` (e.g.,
-  adding/removing projects doesn't affect the hash of existing projects). Defaults to `false`
 
 `runtimeCacheInputs` are set as follows:
 

docs/shared/core-tutorial/01-create-blog.md

@@ -47,17 +47,26 @@ Which tells yarn (or npm) and Nx to look in the `packages` folder for projects t
 
 To install Eleventy run:
 
+{% tabs %}
+{% tab label="yarn" %}
+
 ```bash
 yarn add -D @11ty/eleventy@1.0.0
 ```
 
-or
+{% /tab %}
+{% tab label="npm" %}
 
 ```bash
-npm add -D @11ty/eleventy@1.0.0
+nx generate @nrwl/react:library
 ```
 
-Note: We are intentionally installing the package at the root of the workspace because this forces the organization to have the upfront cost of agreeing on the same versions of dependencies rather than the delayed cost of having projects using multiple different incompatible versions of dependencies. This is not a requirement of Nx, just a suggestion to help you maintain a growing repo.
+{% /tab %}
+{% /tabs %}
+
+{% callout type="check" title="Installing in workspace's root" %}
+We are intentionally installing the package at the root of the workspace because this forces the organization to have the upfront cost of agreeing on the same versions of dependencies rather than the delayed cost of having projects using multiple different incompatible versions of dependencies. This is not a requirement of Nx, just a suggestion to help you maintain a growing repo.
+{% /callout %}
 
 **Eleventy Hello World**
 

docs/shared/core-tutorial/03-share-assets.md

@@ -70,7 +70,7 @@ pageTitle: Some ASCII Art
 Welcome to [The Restaurant at the End of the Universe](https://hitchhikers.fandom.com/wiki/Ameglian_Major_Cow)
 
 <pre>
-{% renderFile "../ascii/assets/cow.txt" %}
+&#123;% renderFile "../ascii/assets/cow.txt" %&#125;
 </pre>
 
 Art courtesy of [cowsay](https://www.npmjs.com/package/cowsay).

docs/shared/daemon.md

@@ -14,7 +14,9 @@ This helps quite a bit, but the recomputation is not very surgical because there
 
 The Nx Daemon is a process which runs in the background on your local machine. There is one unique Nx Daemon per Nx workspace meaning if you have multiple Nx workspaces on your machine active at the same time, the corresponding Nx Daemon instances will operate independently of one another and can be on different versions of Nx.
 
-> On macOS and linux, the server runs as a unix socket, and on Windows it runs as a named pipe.
+{% callout type="note" title="Mac & Linux" %}
+On macOS and linux, the server runs as a unix socket, and on Windows it runs as a named pipe.
+{% /callout %}
 
 The Nx Daemon is more efficient at recomputing the project graph because it watches the files in your workspaces and updates the project graph right away (intelligently throttling to ensure minimal recomputation). It also keeps everything in memory, so the response tends to be a lot faster.
 

docs/shared/eslint.md

@@ -109,4 +109,8 @@ The solution is to update our config once more, this time to set `parserOptions.
 
 And that's it! Now any rules requiring type information will run correctly when we run `nx lint tuskdesk`.
 
-> NOTE: As well as adapting the path to match your project's real path, please be aware that if you apply the above to a **Next.js** application, you should change the glob pattern at the end to be `tsconfig(.*)?.json`. E.g. if `tuskdesk` had been a Next.js app, we would have written: `"project": ["apps/tuskdesk/tsconfig(.*)?.json"]`
+{% callout type="warning" title="Using Next.js" %}
+As well as adapting the path to match your project's real path, please be aware that if you apply the above to a **Next.js** application, you should change the glob pattern at the end to be `tsconfig(.*)?.json`.
+
+E.g. if `tuskdesk` had been a Next.js app, we would have written: `"project": ["apps/tuskdesk/tsconfig(.*)?.json"]`
+{% /callout %}

docs/shared/extending-nx/devkit-and-nx-plugins.md

@@ -3,7 +3,9 @@
 Nx is like the VSCode of build tools. The core of Nx enables project and task graph creation and analysis, orchestration and
 execution of tasks, computation caching, and code generation. [Nx plugins](#nx-plugins) extend this functionality and are built on top of the underlying [Nx Devkit](#nx-devkit).
 
-> Many organizations use Nx without any plugins. If you are mainly interested in making your workspace faster or enabling distributed task execution, then plugins aren't necessary.
+{% callout type="note" title="Plugins are optional" %}
+Many organizations use Nx without any plugins. If you are mainly interested in making your workspace faster or enabling distributed task execution, then plugins aren't necessary.
+{% /callout %}
 
 ## Nx plugins
 
@@ -37,14 +39,22 @@ Plugins have:
   - This allows plugins to add new projects to the workspace when it doesn't contain `workspace.json`, and infer extra
     targets without adding them into project configuration.
 
-All of the core plugins are written using Nx Devkit, and you can use the same utilities to write your own generators and
+All the core plugins are written using Nx Devkit, and you can use the same utilities to write your own generators and
 executors.
 
+{% callout type="check" title="Plugins!" %}
 The Nx team maintains a core set of plugins for many application and tooling frameworks. You can write [custom generators](/generators/workspace-generators) and [executors](/executors/creating-custom-builders) for your own workspace. You can also write your own plugin and share it with the community. The [Nx Plugin](/packages/nx-plugin) plugin provides guidance on how you can build your own custom plugins.
+{% /callout %}
 
 ### Local workspace plugins
 
-Nx plugins can also be used in the workspace they are generated inside of. For example, if you generate a plugin with `nx g @nrwl/nx-plugin:plugin my-plugin --importPath @my-org/my-plugin`, you will be able to immediately make use of generators and executors within it. This would look like `nx g @my-org/my-plugin:lib` for generators or `"executor": "@my-org/my-plugin:build"` for executors. If you are only planning on making use of generators, Nx provides workspace generators which can be used rather than whole plugins. Generating a full plugin allows you to take advantage of all of the capabilities above, including project inference and graph extension, which is not possible when solely using workspace generators. Additionally, your local plugin could be set as the default collection in `nx.json`, such that running `nx g lib` would call your workspace plugin's lib generator.
+Nx plugins can also be used in the workspace they are generated inside of. For example, if you generate a plugin with `nx g @nrwl/nx-plugin:plugin my-plugin --importPath @my-org/my-plugin`, you will be able to immediately make use of generators and executors within it. This would look like `nx g @my-org/my-plugin:lib` for generators or `"executor": "@my-org/my-plugin:build"` for executors.
+
+If you are only planning on making use of generators, Nx provides workspace generators which can be used rather than whole plugins.
+
+Generating a full plugin allows you to take advantage of all of the capabilities above, including project inference and graph extension, which is not possible when solely using workspace generators.
+
+Additionally, your local plugin could be set as the default collection in `nx.json`, such that running `nx g lib` would call your workspace plugin's lib generator.
 
 ### Listing Nx plugins
 

docs/shared/extending-nx/project-graph-plugins.md

@@ -1,6 +1,8 @@
 # Extending the Project Graph of Nx
 
-> This API is experimental and might change.
+{% callout type="caution" title="Experimental" %}
+This API is experimental and might change.
+{% /callout %}
 
 The Project Graph is the representation of the source code in your repo. Projects can have files associated with them. Projects can have dependencies on each other.
 
@@ -72,7 +74,9 @@ builder.addNode({
 });
 ```
 
-> Note: You can designate any type for the node. This differentiates third party projects from projects in the workspace. If you are writing a plugin for a different language, it's common to use IPC to get the list of nodes which you can then add using the builder.
+{% callout type="note" title="More details" %}
+You can designate any type for the node. This differentiates third party projects from projects in the workspace. If you are writing a plugin for a different language, it's common to use IPC to get the list of nodes which you can then add using the builder.
+{% /callout %}
 
 ## Adding New Dependencies to the Project Graph
 
@@ -91,7 +95,9 @@ import { DependencyType } from '@nrwl/devkit';
 builder.addImplicitDependency('existing-project', 'new-project');
 ```
 
-> Note: Even though the plugin is written in JavaScript, resolving dependencies of different languages will probably be more easily written in their native language. Therefore, a common approach is to spawn a new process and communicate via IPC or `stdout`.
+{% callout type="note" title="More details" %}
+Even though the plugin is written in JavaScript, resolving dependencies of different languages will probably be more easily written in their native language. Therefore, a common approach is to spawn a new process and communicate via IPC or `stdout`.
+{% /callout %}
 
 Because an implicit dependency is not associated with any file, Nx doesn't know when it might change, so it will be recomputed every time.
 
@@ -114,7 +120,9 @@ If a file hasn't changed since the last invocation, it doesn't need to be reanal
 
 ## Visualizing the Project Graph
 
-You can then visualize the project graph as described [here](/structure/dependency-graph). However, there is a cache that Nx uses to avoid recalculating the project graph as much as possible. As you develop your project graph plugin, it might be a good idea to set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`. It might also be a good idea to ensure that the dep graph is not running on the nx daemon by setting `NX_DAEMON=false`, as this will ensure you will be able to see any `console.log` statements you add as you're developing.
+You can then visualize the project graph as described [here](/structure/dependency-graph). However, there is a cache that Nx uses to avoid recalculating the project graph as much as possible. As you develop your project graph plugin, it might be a good idea to set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`.
+
+It might also be a good idea to ensure that the dep graph is not running on the nx daemon by setting `NX_DAEMON=false`, as this will ensure you will be able to see any `console.log` statements you add as you're developing.
 
 ## Example Project Graph Plugin
 

docs/shared/extending-nx/project-inference-plugins.md

@@ -1,6 +1,8 @@
 # Project Inference
 
-> This API is experimental and might change.
+{% callout type="caution" title="Experimental" %}
+This API is experimental and might change.
+{% /callout %}
 
 Project inference describes the ability of Nx to discover and work with projects based on source code and configuration files in your repo.
 
@@ -26,7 +28,7 @@ Project file patterns are used in two scenarios:
 - Inferring projects when `workspace.json` is not present
 - Determining which files should be passed into `registerProjectTargets`.
 
-Lets use the below plugin and workspace layout as an example:
+Let's use the below plugin and workspace layout as an example:
 
 > libs/awesome-plugin/index.ts
 
@@ -91,10 +93,16 @@ It is possible that the registerProjectTargets function may be called multiple t
 - One plugin may list multiple file patterns, and a project may match more than one of them.
 - Multiple plugins may list similar patterns, and pick up the project separately.
 
-In the first case, the plugin that you are writing will be called into multiple times. If you return the same target (e.g. `build`) on each call, whichever is ran last would be the target that Nx calls into. The order that the function would be called is **NOT** guaranteed, so you should try to avoid this when possible. If specifying multiple patterns, they should either be mutually exclusive (e.g. one match per project) or the plugin should conditionally add targets based on the file passed in.
+**In the first case**, the plugin that you are writing will be called into multiple times. If you return the same target (e.g. `build`) on each call, whichever is ran last would be the target that Nx calls into.
 
-In the second case, different plugins may attempt to register the same target on a project. If this occurs, whichever target was registered by the plugin listed latest in `nx.json` would be the one called into by Nx. As an example, assume `plugin-a`, `plugin-b`, and `plugin-c` all match a file and register `build` as a target. If `nx.json` included `"plugins": ["plugin-a", "plugin-b", "plugin-c"]`, running `nx build my-project` would run the target as defined by `"plugin-c"`. Alternatively, if `nx.json` included `"plugins": ["plugin-c", "plugin-b", "plugin-a"]`, running `nx build my-project` would run the target as defined by `"plugin-a"`
+The order that the function would be called is **NOT** guaranteed, so you should try to avoid this when possible. If specifying multiple patterns, they should either be mutually exclusive (e.g. one match per project) or the plugin should conditionally add targets based on the file passed in.
+
+**In the second case**, different plugins may attempt to register the same target on a project. If this occurs, whichever target was registered by the plugin listed latest in `nx.json` would be the one called into by Nx. As an example, assume `plugin-a`, `plugin-b`, and `plugin-c` all match a file and register `build` as a target. If `nx.json` included `"plugins": ["plugin-a", "plugin-b", "plugin-c"]`, running `nx build my-project` would run the target as defined by `"plugin-c"`.
+
+Alternatively, if `nx.json` included `"plugins": ["plugin-c", "plugin-b", "plugin-a"]`, running `nx build my-project` would run the target as defined by `"plugin-a"`.
 
 ## Development Tips
 
-There is a cache that Nx uses to avoid recalculating the project graph as much as possible, but it may need to be skipped during plugin development. You can set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`. It might also be a good idea to ensure that the dep graph is not running on the nx daemon by setting `NX_DAEMON=false`, as this will ensure you will be able to see any `console.log` statements you add as you're developing. You can also leave the daemon active, but `console.log` statements would only appear in its log file.
+There is a cache that Nx uses to avoid recalculating the project graph as much as possible, but it may need to be skipped during plugin development. You can set the following environment variable to disable the project graph cache: `NX_CACHE_PROJECT_GRAPH=false`.
+
+It might also be a good idea to ensure that the dep graph is not running on the nx daemon by setting `NX_DAEMON=false`, as this will ensure you will be able to see any `console.log` statements you add as you're developing. You can also leave the daemon active, but `console.log` statements would only appear in its log file.

docs/shared/generators/creating-files.md

@@ -63,7 +63,9 @@ The exported function first creates the library, then creates the additional fil
 
 Next, run the generator:
 
-> Use the `-d` or `--dry-run` flag to see your changes without applying them.
+{% callout type="warning" title="Always do a dry-run" %}
+Use the `-d` or `--dry-run` flag to see your changes without applying them. This will let you see what the command will do to your workspace.
+{% /callout %}
 
 ```bash
 nx workspace-generator my-generator mylib

docs/shared/generators/workspace-generators.md

@@ -1,8 +1,16 @@
-> In Nx 13.10, we introduced the ability to run generators from Nx plugins in the workspace they were created in. By using a "local" plugin, you can set the plugin as your workspace's default collection and get several other affordances that are not provided to workspace generators. This is the preferred method for "workspace generators", and existing generators will eventually be transitioned to use a local plugin. Check the [nx-plugin guide](/packages/nx-plugin) for information on creating a new plugin.
+{% callout type="check" title="Local Nx plugins" %}
+In Nx 13.10, we introduced the ability to run generators from Nx plugins in the workspace they were created in.
+
+By using a "local" plugin, you can set the plugin as your workspace's default collection and get several other affordances that are not provided to workspace generators. This is the preferred method for "workspace generators", and existing generators will eventually be transitioned to use a local plugin.
+
+Check the [nx-plugin guide](/packages/nx-plugin) for information on creating a new plugin.
+{% /callout %}
 
 # Workspace Generators
 
-Workspace generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, or ensuring libraries are generated and structured in a certain way, generators help you standardize these tasks in a consistent, and predictable manner. Nx provides tooling around creating, and running custom generators from within your workspace. This guide shows you how to create, run, and customize workspace generators within your Nx workspace.
+Workspace generators provide a way to automate many tasks you regularly perform as part of your development workflow. Whether it is scaffolding out components, features, or ensuring libraries are generated and structured in a certain way, generators help you standardize these tasks in a consistent, and predictable manner.
+
+Nx provides tooling around creating, and running custom generators from within your workspace. This guide shows you how to create, run, and customize workspace generators within your Nx workspace.
 
 ## Creating a workspace generator
 

docs/shared/getting-started/nx-and-angular.md

@@ -13,7 +13,9 @@ Check out the following guides to get started:
 - [Adding Nx to an Angular CLI project](/migration/migration-angular)
 - [Migrating from AngularJS](/migration/migration-angularjs)
 
+{% callout type="note" title="Going deeper" %}
 It is also a good idea to read the [mental model guide](/using-nx/mental-model) to understand how Nx works.
+{% /callout %}
 
 ## Nx and Angular Plugins
 
@@ -33,7 +35,9 @@ Check out the following to get started:
 
 ## Nx and Angular CLI
 
-**If you add Nx to an Angular CLI project, `ng` and `nx` are interchangeable (they invoke the same command). So anywhere you see `"nx build"` or `"nx affected"`, you can also use `"ng build"` or `"ng affected"`.**
+{% callout type="check" title="Nx and AngularCLI commands are interchangeable" %}
+If you add Nx to an Angular CLI project, `ng` and `nx` are interchangeable (they invoke the same command). So anywhere you see `"nx build"` or `"nx affected"`, you can also use `"ng build"` or `"ng affected"`.
+{% /callout %}
 
 Nx integrates well with the Angular CLI:
 
@@ -56,7 +60,9 @@ What we recommend instead is to split `angular.json` into multiple `project.json
 - Run `nx format`
 - Run `nx generate @nrwl/workspace:convert-to-nx-project --all=true`
 
-**But regardless of whether you use `angular.json` or `project.json`, the configuration remains the same. So anything written about `project.json` or `workspace.json` applies to `angular.json` in the same way. For instance, everything in [project.json and nx.json](/configuration/projectjson) applies to `angular.json` in the same way.**
+{% callout type="check" title="Nx and AngularCLI are compatible" %}
+But regardless of whether you use `angular.json` or `project.json`, the configuration remains the same. So anything written about `project.json` or `workspace.json` applies to `angular.json` in the same way. For instance, everything in [project.json and nx.json](/configuration/projectjson) applies to `angular.json` in the same way.
+{% /callout %}
 
 Note that even though the configuration is split, everything works the same way. All migrations and schematics that expect a single `angular.json` file, will receive a single file. Nx is smart, so it merges all the files in memory to make those migrations and schematics work.
 

docs/shared/getting-started/nx-and-react.md

@@ -12,7 +12,9 @@ Check out the following guides to get started:
 - [Adding Nx to an existing monorepo](/migration/adding-to-monorepo)
 - [Migrating from CRA](/migration/migration-cra)
 
+{% callout type="note" title="Going deeper" %}
 It is also a good idea to read the [mental model guide](/using-nx/mental-model) to understand how Nx works.
+{% /callout %}
 
 ## Nx and React Plugins
 

docs/shared/guides/environment-variables.md

@@ -257,8 +257,9 @@ For example in `project.json` (or `angular.json`),
 }
 ```
 
-> You can also customize your webpack configuration, similar to using `DefinePlugin` above. This approach will require
+{% callout type="note" title="Optimize" %}
-> post-processing the `index.html` file, and is out of scope for this guide.
+You can also customize your webpack configuration, similar to using `DefinePlugin` above. This approach will require post-processing the `index.html` file, and is out of scope for this guide.
+{% /callout %}
 
 ## Summary
 

docs/shared/guides/misc-ngrx.md

@@ -17,7 +17,9 @@ The `ngrx` schematic generates an NgRx feature set containing the following file
 - `selectors` - Composable functions that select pieces of state and update when their inputs change.
 - `facade` - Optional class that provides further encapsulation of NgRx from your component.
 
-> The `ngrx` schematic only provides a sub-set of schematics for the NgRx libraries. See [@ngrx/schematics](https://ngrx.io/guide/schematics) for the full set of available schematics.
+{% callout type="note" title="Schematics" %}
+The `ngrx` schematic only provides a sub-set of schematics for the NgRx libraries. See [@ngrx/schematics](https://ngrx.io/guide/schematics) for the full set of available schematics.
+{% /callout %}
 
 ## Command
 
@@ -27,7 +29,9 @@ The following command is used to run the `ngrx` schematic:
 nx g @nrwl/angular:ngrx <featurename> --module=<path-to-module> --no-interactive [options]
 ```
 
-> Note: the `name` and the `--module=` arguments are required. The `no-interactive` option chooses the recommended defaults for the schematic, unless you override them.
+{% callout type="note" title="Command" %}
+The `name` and the `--module=` arguments are required. The `no-interactive` option chooses the recommended defaults for the schematic, unless you override them.
+{% /callout %}
 
 The most common additional options are:
 
@@ -78,7 +82,9 @@ To manage the feature state:
 nx g @nrwl/angular:ngrx products --module=libs/products/src/lib/products.module.ts --directory +state/products --no-interactive
 ```
 
-> Use the `--facade` option to generate an injectable Facade class along with the feature.
+{% callout type="note" title="Enabling Facades" %}
+Use the `--facade` option to generate an injectable Facade class along with the feature.
+{% /callout %}
 
 The following files are created, or updated:
 
@@ -116,4 +122,6 @@ The feature library's barrel `index.ts` is also updated to export the updated _p
 - The NgRx feature reducer.
 - The optional facade class for the NgRx feature.
 
-> When generating multiple feature states within a single library, make sure there are no naming collisions in the barrel `index.ts` file.
+{% callout type="warning" title="Naming collisions" %}
+When generating multiple feature states within a single library, make sure there are no naming collisions in the barrel `index.ts` file.
+{% /callout %}

docs/shared/guides/module-federation/dynamic-mfe-angular.md

@@ -50,7 +50,9 @@ You'll also be prompted if you would like to setup Nx Cloud. For this tutorial s
 
 To add Angular-related features to our newly created monorepo we need to install the Angular Plugin. Again, this is pretty easy to do:
 
-_**NOTE:** Check that you are now at the root of your monorepo in your terminal. If not, run `cd ng-mfe`_
+{% callout type="warning" title="Be at the root" %}
+Check that you are now at the root of your monorepo in your terminal. If not, run `cd ng-mfe`.
+{% /callout %}
 
 ```bash
 # Npm
@@ -94,9 +96,13 @@ npx nx g @nrwl/angular:remote login --host=dashboard
 yarn nx g @nrwl/angular:remote login --host=dashboard
 ```
 
-_**Note:** We provided `--host=dashboard` as an option. This tells the generator that this remote application will be consumed by the Dashboard application. The generator will automatically link these two applications together in the `module-federation.config.js` that gets used in the `webpack.config.js`._
+{% callout type="note" title="--host" %}
+We provided `--host=dashboard` as an option. This tells the generator that this remote application will be consumed by the Dashboard application. The generator will automatically link these two applications together in the `module-federation.config.js` that gets used in the `webpack.config.js`.\_
+{% /callout %}
 
-_**Note**: The `RemoteEntryModule` generated will be imported in `app.module.ts` file, however, it is not used in the `AppModule` itself. This is to allow TS to find the Module during compilation, allowing it to be included in the built bundle. This is required for the Module Federation Plugin to expose the Module correctly. You can choose to import the `RemoteEntryModule` in the `AppModule` if you wish, however, it is not necessary._
+{% callout type="note" title="More details" %}
+The `RemoteEntryModule` generated will be imported in `app.module.ts` file, however, it is not used in the `AppModule` itself. This is to allow TS to find the Module during compilation, allowing it to be included in the built bundle. This is required for the Module Federation Plugin to expose the Module correctly. You can choose to import the `RemoteEntryModule` in the `AppModule` if you wish, however, it is not necessary.\_
+{% /callout %}
 
 ## What was generated?
 
@@ -281,7 +287,9 @@ export class RemoteEntryComponent {
 }
 ```
 
-_**Note:** This could be improved with error handling etc. but for the purposes of this tutorial, we'll keep it simple._
+{% callout type="note" title="More details" %}
+This could be improved with error handling etc. but for the purposes of this tutorial, we'll keep it simple.
+{% /callout %}
 
 Let's add a route to our Login application so that we can render the `RemoteEntryComponent`.  
 Open `app.module.ts` and add the following route to the `RouterMoodule.forRoot(...)` declaration.
@@ -318,7 +326,9 @@ Now let's create the Dashboard application where we'll hide some content if the
 For this to work, the state within `UserService` must be shared across both applications. Usually, with Module Federation in Webpack, you have to specify the packages to share between all the applications in your Micro Frontend solution.  
 However, by taking advantage of Nx's project graph, Nx will automatically find and share the dependencies of your applications.
 
-_**Note:** This helps to enforce a single version policy and reduces the risk of [Micro Frontend Anarchy](https://www.thoughtworks.com/radar/techniques/micro-frontend-anarchy)_
+{% callout type="note" title="More details" %}
+This helps to enforce a single version policy and reduces the risk of [Micro Frontend Anarchy](https://www.thoughtworks.com/radar/techniques/micro-frontend-anarchy)\_
+{% /callout %}
 
 Now, let's delete the `app.component.html` and `app.component.css` files in the Dashboard application. They will not be needed for this tutorial.
 

docs/shared/guides/module-federation/faster-builds.md

@@ -56,7 +56,9 @@ npx create-nx-workspace acme --preset=empty
 cd acme
 ```
 
-> Note: You will be prompted to enable Nx Cloud in the workspace. For the best experience, we highly recommend using Nx Cloud to take advantage of distributed caching and other features it provides.
+{% callout type="check" title="Enabling distributed caching" %}
+You will be prompted to enable Nx Cloud in the workspace. For the best experience, we highly recommend using Nx Cloud to take advantage of distributed caching and other features it provides.
+{% /callout %}
 
 Then, for React users, install the `@nrwl/react` plugin; and for Angular users, install the `@nrwl/angular` plugin.
 
@@ -82,7 +84,9 @@ nx g @nrwl/react:host host --remotes=shop,cart,about
 nx g @nrwl/angular:host host --remotes=shop,cart,about
 ```
 
-> Note: You can leave off the `--remotes` option and add them later with `nx g @nrwl/react:remote shop --host=host` or `nx g @nrwl/angular:remote shop --host=host`.
+{% callout type="note" title="More details" %}
+You can leave off the `--remotes` option and add them later with `nx g @nrwl/react:remote shop --host=host` or `nx g @nrwl/angular:remote shop --host=host`.
+{% /callout %}
 
 Now, serve `host` to view it in your browser.
 
@@ -100,7 +104,9 @@ nx serve host --open --devRemotes=shop,cart
 
 The above command starts the `shop` and `cart` remotes in development mode, but `about` will remain static.
 
-> Note: Both commands serve the whole system. By passing `--devRemotes`, you configure what parts of it you will be changing. For instance, in the example above, you can go to the about page and back. This is different from having different versions of the app for every team.
+{% callout type="note" title="More details" %}
+Both commands serve the whole system. By passing `--devRemotes`, you configure what parts of it you will be changing. For instance, in the example above, you can go to the about page and back. This is different from having different versions of the app for every team.
+{% /callout %}
 
 ## What was generated?
 
@@ -151,7 +157,9 @@ module.exports = {
 
 The required `name` property is the magic to link the host and remotes together. The `host` application references the three remotes by their names.
 
-> Note: It is important that the values in `remotes` property matches the `name` property of the remote applications. Otherwise, webpack will throw an error. Nx handles this automatically for you so there shouldn't be an issue unless it was modified manually.
+{% callout type="note" title="More details" %}
+It is important that the values in `remotes` property matches the `name` property of the remote applications. Otherwise, webpack will throw an error. Nx handles this automatically for you so there shouldn't be an issue unless it was modified manually.
+{% /callout %}
 
 ## What does `withModuleFederation` do?
 
@@ -184,11 +192,13 @@ module.exports = {
 
 The `shared` function can return an `undefined` to use Nx's default value, `false` to exclude it from being shared, or a [shared config](https://webpack.js.org/plugins/module-federation-plugin/#sharing-hints) that webpack supports.
 
-> Note: The default configuration, without overrides, should work well for most workspaces, and we encourage you to analyze your bundles before optimizing the shared behavior.
+{% callout type="note" title="Analysis" %}
->
+The default configuration, without overrides, should work well for most workspaces, and we encourage you to analyze your bundles before optimizing the shared behavior.
-> To analyze your bundle, run build with `--statsJson` and use a tool like [`webpack-bundle-analyzer`](https://www.npmjs.com/package/webpack-bundle-analyzer) to the size of your bundles.
+
->
+To analyze your bundle, run build with `--statsJson` and use a tool like [`webpack-bundle-analyzer`](https://www.npmjs.com/package/webpack-bundle-analyzer) to the size of your bundles.
-> If you have any feedback regarding this feature, we'd love to hear from you--check our [community page](https://nx.dev/community) for links to our Slack and Twitter.
+
+If you have any feedback regarding this feature, we'd love to hear from you--check our [community page](https://nx.dev/community) for links to our Slack and Twitter.
+{% /callout %}
 
 ## Distributed computation caching with Nx Cloud
 
@@ -225,7 +235,11 @@ If you inspect the terminal output, you'll see something like this, even if you
 
 ```
 
-> This caching behavior is _crucial_. If you don't have a build system supporting distributed computation caching, using Module Federation will be slower. It takes longer to build `shop`, `cart` and `about` separately than building all of them together as part of the same process. **When using Nx, you rarely have to build all of them because most of the time you work on one remote, other remotes will be retrieved from cache.**
+{% callout type="note" title="More details" %}
+This caching behavior is _crucial_. If you don't have a build system supporting distributed computation caching, using Module Federation will be slower. It takes longer to build `shop`, `cart` and `about` separately than building all of them together as part of the same process.
+
+**When using Nx, you rarely have to build all of them because most of the time you work on one remote, other remotes will be retrieved from cache.**
+{% /callout %}
 
 This also helps things like end-to-end (E2E) testing because testing against a static server is much more efficient than starting many servers in development mode. When the CI pipeline runs E2E tests, all the remotes should be served statically from cache.
 
@@ -270,7 +284,9 @@ module.exports = withModuleFederation({
 
 Now you can run `nx build host` to build all the `host` and all the implicit dependencies in production mode.
 
-> Again, if you don't use [Nx Cloud's Distributed Tasks Execution](/using-nx/dte) using Module Federation will be slower than building everything in a single process. It's only if you enable Distributed Tasks Execution, your CI will be able to build each remote on a separate machine, in parallel, (or not build it at all and retrieve it from cache), which will reduce the CI time.
+{% callout type="note" title="Distributed caching" %}
+Again, if you don't use [Nx Cloud's Distributed Tasks Execution](/using-nx/dte) using Module Federation will be slower than building everything in a single process. It's only if you enable Distributed Tasks Execution, your CI will be able to build each remote on a separate machine, in parallel, (or not build it at all and retrieve it from cache), which will reduce the CI time.
+{% /callout %}
 
 After running that command you'll see the following artifacts in `dist` folder.
 

docs/shared/guides/module-federation/micro-frontend-architecture.md

@@ -127,7 +127,9 @@ module.exports = {
 };
 ```
 
-**Note:** You can return any configuration [object that webpack's Module Federation supports](https://webpack.js.org/plugins/module-federation-plugin/#sharing-hints).
+{% callout type="note" title="More details" %}
+You can return any configuration [object that webpack's Module Federation supports](https://webpack.js.org/plugins/module-federation-plugin/#sharing-hints).
+{% /callout %}
 
 There are downsides to not sharing a library (such as increasing network traffic due to duplication), so consider what
 you share carefully. If you are not sure, then start with a small set of core libraries, and expand it as needed.

docs/shared/guides/nx-and-ts.md

@@ -4,7 +4,9 @@
 
 The `@nrwl/js` package ships with corresponding generators and executors that best work when it comes to developing TypeScript applications and libraries.
 
-> Note, you can also opt out of TypeScript and use plain JavaScript by passing the `--js` flag to the generators.
+{% callout type="note" title="Want to use plane Javascript instead?" %}
+Note, you can also opt out of TypeScript and use plain JavaScript by passing the `--js` flag to the generators.
+{% /callout %}
 
 {% youtube
 src="https://www.youtube.com/embed/-OmQ-PaSY5M"
@@ -199,7 +201,9 @@ nx publish publish-me --ver=<required-version> --tag=[custom-tag]
 
 Thanks to [“Target Dependencies” (`dependsOn`)](/configuration/projectjson#dependson) property under the `publish` target, Nx runs the `build` target automatically before Nx runs `publish`. And of course, if `build` has already run, it won't execute again, thanks to [Nx computation caching](/using-nx/caching).
 
-> The generated `publish.mjs` script is a minimal version of what a publishing process looks like. You can definitely add more to it as you see fit for your project. For example: you can add a capability to automatic increment the version
+{% callout type="note" title="Only to get you started" %}
+The generated `publish.mjs` script is a minimal version of what a publishing process looks like. You can definitely add more to it as you see fit for your project. For example: you can add a capability to automatic increment the version.
+{% /callout %}
 
 ### Manual setup
 

docs/shared/guides/nx-devkit-angular-devkit.md

@@ -1,6 +1,8 @@
 # Nx Devkit and Angular Devkit
 
-> Note: this document covers the difference between Nx Devkit and Angular Devkit. See the [Nx Devkit](/devkit/index) guide for more in-depth details about Nx Devkit.
+{% callout type="note" title="Nx & Angular" %}
+This document covers the difference between Nx Devkit and Angular Devkit. See the [Nx Devkit](/devkit/index) guide for more in-depth details about Nx Devkit.
+{% /callout %}
 
 Nx comes with a devkit to write generators and executors, but you can also use Angular devkit (schematics and builders). In other words, you can use an Angular schematic to implement a generator, and you can use an Angular builder to implement an executor.
 

docs/shared/guides/setup-incremental-builds-angular.md

@@ -3,7 +3,9 @@
 In this guide we’ll specifically look into which changes need to be made to enable incremental builds for Angular
 applications.
 
-> Incremental builds requires Nx version 10.4.0 or later.
+{% callout type="caution" title="Nx > 10.4.0" %}
+Incremental builds requires Nx version 10.4.0 or later.
+{% /callout %}
 
 ## Requirements
 
@@ -23,11 +25,9 @@ must have already been run. You can check your `package.json` and make sure you
 }
 ```
 
-> Please note that `ngcc` doesn’t
+{% callout type="warning" title="ngcc limitations" %}
-> support `pnpm` ([#32087](https://github.com/angular/angular/issues/32087#issuecomment-523225437)
+Please note that `ngcc` doesn’t support `pnpm` ([#32087](https://github.com/angular/angular/issues/32087#issuecomment-523225437) and [#38023](https://github.com/angular/angular/issues/38023#issuecomment-732423078)), so you need to use either `yarn` or `npm`.
-> and [#38023](https://github.com/angular/angular/issues/38023#issuecomment-732423078)), so you need to use
+{% /callout %}
-> either `yarn`
-> or `npm`.
 
 ## Use buildable libraries
 
@@ -66,14 +66,11 @@ builds scenario:
 },
 ```
 
-> Please note that it is important to keep the `outputs` property in sync with the `dest` property in the
+{% callout type="warning" title="More details" %}
-> file `ng-package.json` located inside the library root. When a library is generated, this is configured correctly, but
+Please note that it is important to keep the `outputs` property in sync with the `dest` property in the file `ng-package.json` located inside the library root. When a library is generated, this is configured correctly, but if the path is later changed in `ng-package.json`, it needs to be updated as well in the project configuration.
-> if the path is later changed in `ng-package.json`, it needs to be updated as well in the project configuration.
 
-> The `@nrwl/angular:package` executor also supports incremental builds. It is used to build and package an Angular
+The `@nrwl/angular:package` executor also supports incremental builds. It is used to build and package an Angular library to be distributed as an NPM package following the Angular Package Format (APF) specification. It will be automatically configured when generating a publishable library (`nx g @nrwl/angular:lib my-lib --publishable --importPath my-lib`).
-> library to be distributed as an NPM package following the Angular Package Format (APF) specification. It will be
+{% /callout %}
-> automatically configured when generating a publishable
-> library (`nx g @nrwl/angular:lib my-lib --publishable --importPath my-lib`).
 
 ## Adjust the application executor
 

docs/shared/guides/turbo-and-nx.md

@@ -2,7 +2,9 @@
 
 Turborepo is a build tool that has just been released (Dec 2021). It borrows many ideas from Nx, so, naturally, some folks will compare Nx and Turborepo. This document provides some context to help you evaluate what works best for you.
 
-> Note that the relationship between Nx and Turborepo isn’t the same as with Nx and say Yarn workspaces or Lerna. Nx and Yarn workspaces are complementary, so it makes sense to use both in some situations. Turborepo is a subset of Nx (at this point), so we don’t think it makes sense to use both.
+{% callout type="warning" title="Few key differences" %}
+Note that the relationship between Nx and Turborepo isn’t the same as with Nx and say Yarn workspaces or Lerna. Nx and Yarn workspaces are complementary, so it makes sense to use both in some situations. Turborepo is a subset of Nx (at this point), so we don’t think it makes sense to use both.
+{% /callout %}
 
 We do our best to be unbiased, but, of course you should do your own research. Read the docs, try things out, etc.
 

docs/shared/guides/using-tailwind-css-with-angular-projects.md

@@ -22,7 +22,9 @@ The generation for existing or new projects will perform the following steps:
   - Applications: update the application styles entry point file located at `apps/app1/src/styles.css` by including the Tailwind CSS base styles
   - Libraries: add the `tailwind.config.js` file path to the `build` target configuration
 
-> **Note**: When Tailwind CSS has not been installed yet, the generator will install Tailwind CSS v3. Only if Tailwind CSS v2 is installed, the generator will use it and generate the configuration accordingly.
+{% callout type="note" title="More details" %}
+When Tailwind CSS has not been installed yet, the generator will install Tailwind CSS v3. Only if Tailwind CSS v2 is installed, the generator will use it and generate the configuration accordingly.
+{% /callout %}
 
 > All the examples in this guide will use Tailwind CSS v3, but the guide will work the same for v2. To convert the examples to v2, check the [Tailwind CSS upgrade guide](https://tailwindcss.com/docs/upgrade-guide#migrating-to-the-jit-engine) to understand the differences between the configuration for both versions.
 
@@ -145,7 +147,9 @@ module.exports = {
 };
 ```
 
-> **Note**: The `content` property shouldn't be specified in the preset because its value is not common for multiple projects.
+{% callout type="note" title="More details" %}
+The `content` property shouldn't be specified in the preset because its value is not common for multiple projects.
+{% /callout %}
 
 Add the project configuration for the project:
 
@@ -238,9 +242,13 @@ To configure Tailwind CSS for multiple applications that use different themes an
 
 A key aspect in this scenario is that because the same buildable libraries are shared by multiple applications, you need to make sure those libraries use Tailwind CSS utility classes and/or theme keys that are common to all the applications that consume them.
 
-> **Note**: Different applications can still have some extra configuration unique to them, but the unique configuration can't be used by shared libraries, because it's not going to be available for other applications.
+{% callout type="note" title="Configuration" %}
+Different applications can still have some extra configuration unique to them, but the unique configuration can't be used by shared libraries, because it's not going to be available for other applications.
+{% /callout %}
 
-> **Note**: As explained in [this section](#configure-tailwind-css-for-an-application-with-non-buildable-libraries-as-dependencies), non-buildable libraries are processed as part of the application build process and therefore, they just use the same configuration the application uses.
+{% callout type="note" title="Non buildable libraries" %}
+As explained in [this section](#configure-tailwind-css-for-an-application-with-non-buildable-libraries-as-dependencies), non-buildable libraries are processed as part of the application build process and therefore, they just use the same configuration the application uses.
+{% /callout %}
 
 Create a new folder `libs/tailwind-preset` with a `tailwind.config.js` file in it with your shared configuration:
 
@@ -440,7 +448,9 @@ To build and share a theme, you can create a theme file in the library like the
 }
 ```
 
-> **Note**: This section assume you've already followed one of the previous sections setup and have the library with Tailwind CSS configured.
+{% callout type="note" title="More details" %}
+This section assume you've already followed one of the previous sections setup and have the library with Tailwind CSS configured.
+{% /callout %}
 
 Next, you need to configure your project to build the theme when you build the library. Edit the project configuration to have the following targets:
 
@@ -508,7 +518,9 @@ Next, you need to configure your project to build the theme when you build the l
 
 In the above, you are configuring the library build and the Tailwind CSS processing to happen in parallel. Also, you are going to disable the automatic deletion of the output folder that `ng-packagr` does because that can cause the theme to be deleted. Instead, you configured the `build` target to delete the output folder and then kick off the library build.
 
-> **Note**: You can have more themes and simply add them to be built in the `build-lib` target commands.
+{% callout type="note" title="Need more?" %}
+You can have more themes and simply add them to be built in the `build-lib` target commands.
+{% /callout %}
 
 Update the `libs/lib1/ng-package.json` file to set the `deleteDestPath` property to `false`:
 
@@ -526,4 +538,6 @@ One important thing to keep in mind is that if you use the default Tailwind CSS
 - Add a unique [prefix](https://tailwindcss.com/docs/configuration#prefix) to your Tailwind CSS utility classes.
 - Create unique CSS classes for your components and theme in general using a Tailwind CSS directive like [`@apply`](https://tailwindcss.com/docs/functions-and-directives#apply) or a function like [`theme()`](https://tailwindcss.com/docs/functions-and-directives#theme).
 
-> **Note**: If you decide to use a unique prefix, remember to change the utility classes used in your components to use the prefix.
+{% callout type="note" title="Prefix" %}
+If you decide to use a unique prefix, remember to change the utility classes used in your components to use the prefix.
+{% /callout %}

docs/shared/guides/why-monorepos.md

@@ -2,7 +2,9 @@
 
 A monorepo is a single git repository that holds the source code for multiple applications and libraries, along with the tooling for them.
 
-> If you are familiar with Lerna or Yarn workspaces, check out [this guide](/guides/lerna-and-nx) (with a quick video) showing how to add Nx to a Lerna/Yarn workspace, what the difference is, when to use both and when to use just Nx.
+{% callout type="note" title="Lerna users" %}
+If you are familiar with Lerna or Yarn workspaces, check out [this guide](/guides/lerna-and-nx) (with a quick video) showing how to add Nx to a Lerna/Yarn workspace, what the difference is, when to use both and when to use just Nx.
+{% /callout %}
 
 ## What are the benefits of a monorepo?
 

docs/shared/incremental-builds.md

@@ -64,8 +64,6 @@ The downsides of incremental builds:
 
 If you are only planning to use incremental builds to speed up your CI, then the watch mode concern is irrelevant, and the only thing you need to assess is whether the benefits of skipping the compilation outweigh the costs of initializing the TypeScript compiler several times.
 
-> For a given workspace you can use Nx batch mode executors to compile all the libs using a single TS program. It can be made to work for a single workspace, but it's hard to generalize. With this, there is only one TS program created, so there is no extra cost associated with incremental builds.
-
 ## Custom Serve Target
 
 If you are implementing a custom serve command, you can use `WebpackNxBuildCoordinationPlugin` provided by `@nrwl/web`. It's a webpack plugin you can use to coordinate the compiling of the libs and the webpack linking.

docs/shared/migration/adding-to-monorepo.md

@@ -1,8 +1,8 @@
 # Adding Nx to Lerna/Yarn/PNPM/NPM Workspace
 
-> Interested in migrating from [Lerna](https://github.com/lerna/lerna) in particular? In case you missed it, Nrwl, the
+{% callout type="note" title="Migrating from Lerna?" %}
-> company behind Nx, [took over stewardship of Lerna](https://blog.nrwl.io/lerna-is-dead-long-live-lerna-61259f97dbd9).
+Interested in migrating from [Lerna](https://github.com/lerna/lerna) in particular? In case you missed it, Nrwl, the company behind Nx, [took over stewardship of Lerna](https://blog.nrwl.io/lerna-is-dead-long-live-lerna-61259f97dbd9). This allows for a much better integration between the two. [Read more in our dedicated guide](/guides/lerna-and-nx).
-> This allows for a much better integration between the two. [Read more in our dedicated guide](/guides/lerna-and-nx).
+{% /callout %}
 
 **Short story:** you can use Nx easily together with your current Lerna/Yarn/PNPM/NPM monorepo setup. Why? To speed up
 your tasks by leveraging Nx's powerful scheduling and caching capabilities.
@@ -28,8 +28,9 @@ width="100%" /%}
 2. Create `nx.json`, containing all the necessary configuration for Nx.
 3. Set up [Nx Cloud](https://nx.app) (if you chose "yes").
 
-> If you are familiar with Turborepo, check out [this guide](/guides/turbo-and-nx). At this point, Nx can do anything
+{% callout type="note" title="Familiar with Turborepo?" %}
-> Turbo can, and much more.
+If you are familiar with Turborepo, check out [this guide](/guides/turbo-and-nx). At this point, Nx can do anything Turbo can, and much more.
+{% /callout %}
 
 ## What You Get Right Away
 

docs/shared/migration/lerna-and-nx.md

@@ -1,6 +1,8 @@
 # Integrating Nx and Lerna
 
-> In case you missed it, Nrwl, the company behind Nx, [took over stewardship of Lerna](https://blog.nrwl.io/lerna-is-dead-long-live-lerna-61259f97dbd9). This opens up a range of new opportunities for integrating the two. Continue reading to learn more.
+{% callout type="check" title="Nrwl took over stewardship of Lerna" %}
+[In case you missed it, Nrwl, the company behind Nx, took over stewardship of Lerna. This opens up a range of new opportunities for integrating the two. Continue reading to learn more](https://blog.nrwl.io/lerna-is-dead-long-live-lerna-61259f97dbd9).
+{% /callout %}
 
 [Lerna](https://lerna.js.org/) is a popular JavaScript monorepo management tool and which can be used in combination with Nx. Lerna does three main things:
 
@@ -10,7 +12,7 @@
 
 While Lerna is good at managing dependencies and publishing, it can quickly become painful to scale Lerna based monorepos, simply because Lerna is slow. That's where Nx shines and where it can really speed up your monorepo.
 
-If you are about to setup a new monorepo from scratch, you can directly [go with Nx](/getting-started/nx-setup). If you have an existing Lerna monorepo, you can easily integrate the two.
+If you are about to set up a new monorepo from scratch, you can directly [go with Nx](/getting-started/nx-setup). If you have an existing Lerna monorepo, you can easily integrate the two.
 
 For a discussion on #2, see [dependency management](#dependency-management) below. For a discussion on #3, see [version management](#version-Management--publishing) below.
 
@@ -81,7 +83,9 @@ Nx works even without `nx.json` but to configure some more details such as the `
 
 Having done these steps, you can now keep using your Lerna repository as you did before. All the commands will work in a backwards compatible way but will be a lot faster. [Read our blog post for some benchmarks](https://blog.nrwl.io/lerna-used-to-walk-now-it-can-fly-eab7a0fe7700?source=friends_link&sk=6c827ec7c9adfc1c760ff2e3f3e05cc7).
 
-> Note, this does not include distributed caching or distributed task execution powered by Nx Cloud. But you can easily add support for it if wanted. All that's required is `npx nx connect-to-nx-cloud`.
+{% callout type="note" title="Enable remote caching?" %}
+This does not include distributed caching or distributed task execution powered by Nx Cloud. But you can easily add support for it if wanted. All that's required is `npx nx connect-to-nx-cloud`.
+{% /callout %}
 
 ### Switch to the Nx native commands in your Lerna workspace
 

docs/shared/migration/manual.md

@@ -31,30 +31,27 @@ Take a tour of your [Nx workspace](/getting-started/nx-setup). There are some im
 
 The `apps` directory is the place where your top-level applications will be stored. You should always begin your migration journey by adding an application.
 
-For Angular applications:
+{% tabs %}
+{% tab label="Angular" %}
 
 ```bash
 npm install --save-dev @nrwl/angular
-```
+# then
-
-and
-
-```bash
 nx generate @nrwl/angular:application my-application
 ```
 
-For React applications:
+{% /tab %}
+{% tab label="React" %}
 
 ```bash
 npm install --save-dev @nrwl/react
-```
+# then
-
-and
-
-```bash
 nx generate @nrwl/react:application my-application
 ```
 
+{% /tab %}
+{% /tabs %}
+
 There are a lot of options when creating your application. If you want to follow Nx recommendations, you can accept the defaults. If you have a well-established codebase, you can configure those options at the time of application generation. You can find documentation for these options for the different frameworks here:
 
 - [Angular](/packages/angular/generators/application)
@@ -182,19 +179,26 @@ Your use-case may also be covered by one of our community plugins. Plugin author
 
 If your code is divided into libraries, you should also generate libraries for your code to migrate into:
 
-For Angular libraries:
+{% tabs %}
+{% tab label="Angular" %}
 
 ```bash
 nx generate @nrwl/angular:library
 ```
 
-For React libraries:
+{% /tab %}
+{% tab label="React" %}
 
 ```bash
 nx generate @nrwl/react:library
 ```
 
+{% /tab %}
+{% /tabs %}
+
+{% callout type="caution" title="Be mindful about where the code lives" %}
 It’s important to remember: don’t just drop your code anywhere! Always generate an app or a library for that code before migration. Without the project configuration, you’ll miss out on key functionalities of Nx provided by the project graph generation and affected code detection.
+{% /callout %}
 
 ### Establishing code boundaries
 

docs/shared/migration/migration-angular.md

@@ -4,7 +4,7 @@ Within an Nx workspace, you gain many capabilities that help you build applicati
 
 ## Prerequisites
 
-- The major version of your `Angular CLI` must align with the version of `Nx` you are upgrading to. For example, if you're using Angular CLI version 7, you must transition using the latest version 7 release of Nx.
+**The major version of your `Angular CLI` must align with the version of `Nx` you are upgrading to**. For example, if you're using Angular CLI version 7, you must transition using the latest version 7 release of Nx.
 
 ## Using the Nx CLI while preserving the existing structure
 

docs/shared/migration/migration-angularjs.md

@@ -14,7 +14,9 @@ For this example, you’ll be migrating the [Real World AngularJS](https://githu
 
 There is also a [repo](https://github.com/nrwl/nx-migrate-angularjs-example) that shows a completed example of this guide.
 
-> The RealWorld app is a great example of an AngularJS app, but it probably doesn’t have the complexity of your own codebase. As you go along, I’ll include some recommendations on how you might apply this example to your larger, more complex application.
+{% callout type="note" title="RealWorld app vs reality" %}
+The RealWorld app is a great example of an AngularJS app, but it probably doesn’t have the complexity of your own codebase. As you go along, I’ll include some recommendations on how you might apply this example to your larger, more complex application.
+{% /callout %}
 
 ## Creating your workspace
 
@@ -43,7 +45,9 @@ npm install -D @nrwl/angular
 
 For this example, we will use Karma and Protractor, the most common unit test runner and e2e test runner for AngularJS.
 
-> Codebases with existing unit and e2e tests should continue to use whatever runner they need. We’ve chosen Karma and Protractor here because it’s the most common. If you’re going to be adding unit testing or e2e as part of this transition and are starting fresh, we recommend starting with Jest and Cypress (the default if no arguments are passed to the above command).
+{% callout type="note" title="Unit & E2E tests" %}
+Codebases with existing unit and e2e tests should continue to use whatever runner they need. We’ve chosen Karma and Protractor here because it’s the most common. If you’re going to be adding unit testing or e2e as part of this transition and are starting fresh, we recommend starting with Jest and Cypress (the default if no arguments are passed to the above command).
+{% /callout %}
 
 With the Angular capability added, generate your application:
 
@@ -58,7 +62,9 @@ Accept the default options for each prompt:
 ? Would you like to configure routing for this application? No
 ```
 
-> The RealWorld app doesn’t have any styles to actually bundle here. They’re all downloaded from a CDN that all of the RealWorld apps use. If your codebase uses something other than CSS, like Sass, you can choose that here.
+{% callout type="note" title="About styles" %}
+The RealWorld app doesn’t have any styles to actually bundle here. They’re all downloaded from a CDN that all the RealWorld apps use. If your codebase uses something other than CSS, like Sass, you can choose that here.
+{% /callout %}
 
 ## Migrating dependencies
 
@@ -142,7 +148,9 @@ Your `package.json` should now look like this:
 
 Run `npm install` to install all of your new dependencies.
 
-> For your own project, you’ll need to switch to NPM if you’re using another package manager like bower. [Learn more about switching away from bower](https://bower.io/blog/2017/how-to-migrate-away-from-bower/)
+{% callout type="caution" title="Using Bower?" %}
+For your own project, you’ll need to switch to NPM if you’re using another package manager like bower. [Learn more about switching away from bower](https://bower.io/blog/2017/how-to-migrate-away-from-bower/)
+{% /callout %}
 
 ## Migrating application code
 
@@ -177,7 +185,9 @@ apps
 | | |____test.ts
 ```
 
-> You most likely have your own AngularJS project written in JavaScript as well. While you’ll continue to use JavaScript through the rest of this example, we strongly recommend switching AngularJS projects to TypeScript, especially if you’re planning an upgrade to Angular.
+{% callout type="warning" title="Javscript vs Typescript" %}
+You most likely have your own AngularJS project written in JavaScript as well. While you’ll continue to use JavaScript through the rest of this example, we strongly recommend switching AngularJS projects to TypeScript, especially if you’re planning an upgrade to Angular.
+{% /callout %}
 
 ## Modifying index.html and main.ts
 
@@ -195,11 +205,15 @@ And re-name it to `main.js`. This will import the existing app.js file from the
 
 If you’re looking at the example repo, the code for this section is available on branch `initial-migration`. This section is an interim step that continues to use gulp to build and serve the app locally, so we can validate everything works before continuing with the migration. You’ll replace gulp in the next section.
 
-> The RealWorld app uses gulp 3.9.1 to build. This version is not supported anymore and doesn’t run on any version of Node greater than 10.\*. To build this app using gulp, you need to install an appropriate version of Node and make sure you re-install your dependencies. If this isn’t possible (or you just don’t want to), feel free to skip to the next section. The webpack build process should run in any modern Node version.
+{% callout type="warning" title="Tools & node versions" %}
+The RealWorld app uses gulp 3.9.1 to build. This version is not supported anymore and doesn’t run on any version of Node greater than 10.\*. To build this app using gulp, you need to install an appropriate version of Node and make sure you re-install your dependencies. If this isn’t possible (or you just don’t want to), feel free to skip to the next section. The webpack build process should run in any modern Node version.
+{% /callout %}
 
 The RealWorld app uses gulp to build the application, as well as provide a development server. To verify that the migration has worked, stay with that build process for now.
 
-> During migration, you should take a small step and confirm that things work before moving ahead. Stopping and checking to see that your app still builds and functions is essential to a successful migration.
+{% callout type="caution" title="Verify your changes" %}
+During migration, you should take a small step and confirm that things work before moving ahead. Stopping and checking to see that your app still builds and functions is essential to a successful migration.
+{% /callout %}
 
 Copy the `gulpfile.js` over from the RealWorld app and put it in `apps/realworld`. This is where all configuration files reside for the application. Make some adjustments to this file so that your build artifacts land in a different place. In an Nx workspace, all build artifacts should be sent to an app-specific folder in the `dist` folder at the root of your workspace. Your `gulpfile.js` should look like this:
 
@@ -335,7 +349,9 @@ nx serve realworld
 
 Navigate around the application and see that things work.
 
-> Your own project might not be using gulp. If you’re using webpack, you can follow the next section and substitute your own webpack configuration. If you’re using something else like grunt or a home-grown solution, you can follow the same steps here to use it. You’ll use the `run-commands` executor and substitute in the commands for your project.
+{% callout type="warning" title="Not using Gulp" %}
+Your own project might not be using gulp. If you’re using webpack, you can follow the next section and substitute your own webpack configuration. If you’re using something else like grunt or a home-grown solution, you can follow the same steps here to use it. You’ll use the `run-commands` executor and substitute in the commands for your project.
+{% /callout %}
 
 ## Switching to webpack
 
@@ -380,7 +396,9 @@ module.exports = (config, context) => {
 };
 ```
 
-> This webpack configuration is deliberately simplified for this tutorial. A real production-ready webpack config for your project will be much more involved. See [this project](https://github.com/preboot/angularjs-webpack) for an example.
+{% callout type="note" title="Webpack configuration" %}
+This webpack configuration is deliberately simplified for this tutorial. A real production-ready webpack config for your project will be much more involved. See [this project](https://github.com/preboot/angularjs-webpack) for an example.
+{% /callout %}
 
 To use webpack instead of gulp, go back to your `apps/realworld/project.json` file and modify the `build` and `serve` commands again:
 
@@ -483,7 +501,9 @@ This change loads the HTML code directly and sets it to the template attribute o
 
 Now, go through each component of the application and make this change. To make sure that you’ve really modified every component correctly, delete the template cache file (`config/app.templates.js`) that gulp generated earlier.
 
-> In an example like this, it’s easy enough to make this kind of change by hand. In a larger codebase, doing this manually could be very time-intensive. You’ll want to look into an automated tool to do this for you, such as js-codemod or generators.
+{% callout type="check" title="Automate the work" %}
+In an example like this, it’s easy enough to make this kind of change by hand. In a larger codebase, doing this manually could be very time-intensive. You’ll want to look into an automated tool to do this for you, such as js-codemod or generators.
+{% /callou %}
 
 We also need to modify the `app.js` and remove the import of `config/app.templates.js`. Modify it like this:
 

docs/shared/migration/migration-cra.md

@@ -4,7 +4,9 @@ Create-React-App (CRA) is the most widely used tool for creating, building and t
 
 You can either use a CLI tool to migrate your app automatically, or you can follow the steps described below to do the migration manually.
 
-**Note:** This guide has been updated for Nx 13 and may not work for earlier versions of Nx.
+{% callout type="caution" title="Nx < 13" %}
+This guide has been updated for Nx 13 and may not work for earlier versions of Nx.
+{% /callout %}
 
 If you have a monorepo (more than one project in the same repo), follow the [Adding Nx to Lerna/Yarn/PNPM/NPM Workspace](https://nx.dev/migration/adding-to-monorepo) guide instead.
 
@@ -21,7 +23,9 @@ npx cra-to-nx
 Then just sit back and wait. After a while, take advantage of the [full magic of Nx](https://nx.dev/getting-started/intro).
 Start from [the commands mentioned in this article](https://nx.dev/migration/migration-cra#try-nx).
 
-**Note:** The command will fail if you try execute it and you have uncommitted changes in your repository. Commit any local changes, and then try to run the command.
+{% callout type="caution" title="Commit your changes" %}
+The command will fail if you try to execute it, and you have uncommitted changes in your repository. Commit any local changes, and then try to run the command.
+{% /callout %}
 
 See it in action:
 
@@ -51,22 +55,36 @@ To start migrating your app, create an Nx workspace:
 npx create-nx-workspace@latest acme --appName=webapp --preset=react --style=css --nx-cloud
 ```
 
-**Note:** Replace `acme` with your organization's npm scope. This will be used when importing workspace projects. You can also replace `webapp` with a different name -- you can have more than one app in an Nx workspace.
+{% callout type="warning" title="Scope & appName?" %}
+Replace `acme` with your organization's npm scope. This will be used when importing workspace projects. You can also replace `webapp` with a different name -- you can have more than one app in an Nx workspace.
+{% /callout %}
 
 ### 2. Add npm packages to your workspace to support CRA
 
 We'll need to add a few dependencies to the Nx workspace that are needed to allow CRA to function.
 
+{% tabs %}
+{% tab label="yarn" %}
+
 ```bash
 yarn add --dev react-scripts @testing-library/jest-dom eslint-config-react-app @craco/craco
 yarn add web-vitals
+```
 
-# Or with npm
+{% /tab %}
+{% tab label="npm" %}
+
+```bash
 npm install --force --save-dev react-scripts @testing-library/jest-dom eslint-config-react-app @craco/craco
 npm install --save web-vitals
 ```
 
-**Note:** The `@craco/craco` package allows us to customize the webpack and jest config without ejecting.
+{% /tab %}
+{% /tabs %}
+
+{% callout type="note" title="Scope & appName?" %}
+The `@craco/craco` package allows us to customize the webpack and jest config without ejecting.
+{% /callout %}
 
 ### 3. Replace code generated by Nx with the CRA app
 
@@ -193,7 +211,9 @@ Update your app's `package.json` file (path: `apps/webapp/package.json`) to use
 }
 ```
 
-**Note:** The `BUILD_PATH` variable is set to be consistent with other Nx projects. This is optional so you can remove it.
+{% callout type="note" title="BUILD_PATH" %}
+The `BUILD_PATH` variable is set to be consistent with other Nx projects. This is optional so you can remove it.
+{% /callout %}
 
 ### 6. Remove targets from project.json
 

docs/shared/monorepo-nx-enterprise.md

@@ -10,7 +10,9 @@ Some things, however, are much more important for large companies:
 - Developer workflow
 - Deployment flexibility
 
-> Everything below are just recommendations. Every large organization has unique needs, so treat this document as a starting point not the definite list of what you must and must not do.
+{% callout type="note" title="Do what is best for you" %}
+Everything below are just recommendations. Every large organization has unique needs, so treat this document as a starting point not the definite list of what you must and must not do.
+{% /callout %}
 
 ## Code Organization & Naming Conventions
 
@@ -194,4 +196,4 @@ Monorepo-style development works best when used with trunk-based development.
 When using trunk-based development, we have a single main branch (say `main`) where every team submits their code. And
 they do it as soon as possible. So if someone works on a large feature, they split it into a few small changes that can be integrated into main in a week. In other words, when using trunk-based development, teams can create branches, but they are short-lived and focus on a specific user story.
 
-One issue folks often raise in regards to trunk-based development is "things change under you while you are trying to create a release". This can definitely happen, especially when manual testing is involved. To mitigate we can create a release branch where we would cherry-pick commits from `main` to. With this, we can still frequently merge code into `main` and have our release isolated from changes made by other teams.
+One issue folks often raise in regard to trunk-based development is "things change under you while you are trying to create a release". This can definitely happen, especially when manual testing is involved. To mitigate we can create a release branch where we would cherry-pick commits from `main` to. With this, we can still frequently merge code into `main` and have our release isolated from changes made by other teams.

docs/shared/monorepo-tags.md

@@ -149,7 +149,7 @@ Projects without any tags cannot depend on any other projects. If you add the fo
 }
 ```
 
-If you try to violate the constrains, you will get an error:
+If you try to violate the constraints, you will get an error:
 
 ```bash
 A project tagged with "scope:admin" can only depend on projects tagged with "scoped:shared" or "scope:admin".

docs/shared/node-tutorial/01-create-application.md

@@ -7,7 +7,9 @@ width="100%" /%}
 
 In this tutorial you use Nx to build a server application out of common libraries using modern technologies.
 
-> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/getting-started/nx-core).
+{% callout type="note" title="Plugins for a rich developer experience" %}
+In this tutorial, we use several Nx plugins to provide a rich developer experience that do most of the work for you. **All the plugins are optional.** [Read about using Nx Core without plugins](/getting-started/nx-core).
+{% /callout %}
 
 ## Create a New Workspace
 
@@ -71,27 +73,41 @@ Depending on how your dev env is set up, the command above might result in `Comm
 
 To fix it, you can either install the `nx` cli globally by running:
 
-```bash
+{% tabs %}
-npm install -g nx
+{% tab label="yarn" %}
-```
-
-or
 
 ```bash
 yarn global add nx
 ```
 
+{% /tab %}
+{% tab label="npm" %}
+
+```bash
+npm install -g nx
+```
+
+{% /tab %}
+{% /tabs %}
+
 Or you can prepend every command with `npm run`:
 
+{% tabs %}
+{% tab label="yarn" %}
+
+```bash
+yarn nx serve todos
+```
+
+{% /tab %}
+{% tab label="npm" %}
+
 ```bash
 npx nx serve todos
 ```
 
-or
+{% /tab %}
-
+{% /tabs %}
-```bash
-yarn nx serve todos
-```
 
 ## Project.json, Targets, Executors
 

docs/shared/node-tutorial/02-display-todos.md

@@ -22,7 +22,9 @@ CREATE apps/todos/src/app/todos/todos.service.ts (89 bytes)
 UPDATE apps/todos/src/app/app.module.ts (318 bytes)
 ```
 
-> Services are not the only things that the `@nrwl/nest` plugin can create. Run `nx list @nrwl/nest` to see other capabilities that the plugin provides.
+{% callout type="check" title="Get more info on plugins" %}
+Services are not the only things that the `@nrwl/nest` plugin can create. Run `nx list @nrwl/nest` to see other capabilities that the plugin provides.
+{% /callout %}
 
 Open the newly created file in `apps/todos/src/app/todos/todos.service.ts` and paste the following code:
 
@@ -47,7 +49,9 @@ export class TodosService {
 }
 ```
 
-> Usually services should call some kind of data source (like a database or even a file) but for this tutorial, just populate todos manually.
+{% callout type="note" title="We keep things simple here" %}
+Usually services should call some kind of data source (like a database or even a file) but for this tutorial, just populate todos manually.
+{% /callout %}
 
 You now have your Todos service ready!
 
@@ -55,16 +59,23 @@ You now have your Todos service ready!
 
 In order to render some views, you need to install a template engine:
 
+{% tabs %}
+{% tab label="yarn" %}
+
 ```bash
 yarn add hbs
 ```
 
-or
+{% /tab %}
+{% tab label="npm" %}
 
 ```bash
 npm install --save hbs
 ```
 
+{% /tab %}
+{% /tabs %}
+
 Once the installation process is complete, you need to configure the `main.ts` file with the following code:
 
 ```typescript
@@ -147,7 +158,9 @@ export class AppController {
 You changed the `@Get` decorator for the `getData` function to point to the `api` route. You also changed this to call the `todosService.getTodos()` method. \
 Then you added the `root` function which renders the `index` file from our `views` directory.
 
-> The serve process should still be running. If it isn't, restart the process with `nx serve todos`
+{% callout type="note" title="Serve is running" %}
+The serve process should still be running. If it isn't, restart the process with `nx serve todos`
+{% /callout %}
 
 ## What's Next
 

docs/shared/node-tutorial/04-create-libs.md

@@ -21,7 +21,9 @@ Run
 nx g @nrwl/nest:lib auth --controller
 ```
 
-> We added the `--controller` flag here to generate a controller along with the library scaffolding.
+{% callout type="note" title="--controller" %}
+We added the `--controller` flag here to generate a controller along with the library scaffolding.
+{% /callout %}
 
 You should see the following:
 
@@ -65,7 +67,9 @@ export class AuthController {
 }
 ```
 
-> In code destined for production, you would actually have a proper authentication check here.
+{% callout type="note" title="We keep things simple here" %}
+In code destined for production, you would actually have a proper authentication check here.
+{% /callout %}
 
 ## Use the new library
 
@@ -87,7 +91,7 @@ import { AuthModule } from '@myorg/auth';
 export class AppModule {}
 ```
 
-**Restart `nx serve todos` then go to http://localhost:3333/auth. You should see `{ authenticated: true }`**
+Restart `nx serve todos` then go to http://localhost:3333/auth. You should see `{ authenticated: true }`.
 
 ## What's Next
 

docs/shared/react-tutorial/01-create-application.md

@@ -7,9 +7,13 @@ width="100%" /%}
 
 In this tutorial you use Nx to build a full-stack application out of common libraries using modern technologies.
 
-> Next.js: Nx also has first-class Next.js support. Read more about it [here](/next/overview)
+{% callout type="check" title="Nx has first-class Next.js support" %}
+Nx has first-class Next.js support, if you are looking to try or use it for your project. Read more about it [here](/next/overview)
+{% /callout %}
 
-> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/getting-started/nx-core).
+{% callout type="note" title="Plugins for a rich developer experience" %}
+In this tutorial, we use several Nx plugins to provide a rich developer experience that do most of the work for you. **All the plugins are optional.** [Read about using Nx Core without plugins](/getting-started/nx-core).
+{% /callout %}
 
 ## Create a new workspace
 
@@ -98,7 +102,7 @@ npx nx serve todos
 
 ## Note on the Nx CLI
 
-If you would prefer to run using a global installation of Nx, you can run:
+If you prefer to run using a global installation of Nx, you can run:
 
 ```bash
 nx serve todos
@@ -108,28 +112,42 @@ Depending on how your dev env is set up, the command above might result in `Comm
 
 To fix it, you can either install the `nx` cli globally by running:
 
-```bash
+{% tabs %}
-npm install -g nx
+{% tab label="yarn" %}
-```
-
-or
 
 ```bash
 yarn global add nx
 ```
 
-Alternatively, you can run the local installation of Nx by prepending every command with `npx`:
+{% /tab %}
+{% tab label="npm" %}
 
 ```bash
-npx nx serve todos
+npm install -g nx
 ```
 
-or
+{% /tab %}
+{% /tabs %}
+
+Alternatively, you can run the local installation of Nx by prepending every command with `npx`:
+
+{% tabs %}
+{% tab label="yarn" %}
 
 ```bash
 yarn nx serve todos
 ```
 
+{% /tab %}
+{% tab label="npm" %}
+
+```bash
+npx nx serve todos
+```
+
+{% /tab %}
+{% /tabs %}
+
 ## What's Next
 
 - Continue to [Step 2: Add E2E Tests](/react-tutorial/02-add-e2e-test)

docs/shared/react-tutorial/05-add-node-app.md

@@ -43,17 +43,26 @@ Nx is an open platform with plugins for many modern tools and frameworks. **To s
 
 **Add the dependency:**
 
-```bash
+{% tabs %}
-npm install --save-dev @nrwl/express
+{% tab label="yarn" %}
-```
-
-or
 
 ```bash
 yarn add --dev @nrwl/express
 ```
 
-> `@nrwl/express` also added `@nrwl/node`. Run `npx nx list @nrwl/express` and `npx nx list @nrwl/node` to see what those plugins provide.
+{% /tab %}
+{% tab label="npm" %}
+
+```bash
+npm install --save-dev @nrwl/express
+```
+
+{% /tab %}
+{% /tabs %}
+
+{% callout type="check" title="List plugins" %}
+When installing `@nrwl/express`, it also automatically added `@nrwl/node` for you. Run `npx nx list @nrwl/express` and `npx nx list @nrwl/node` to see what those plugins provide.
+{% /callout %}
 
 ## Generate an Express application
 
@@ -98,9 +107,11 @@ The `apps` directory is where Nx places anything you can run: frontend applicati
 
 You can run:
 
-- `npx nx serve api` to serve the application
+| Command          | Description           |
-- `npx nx build api` to build the application
+| ---------------- | --------------------- |
-- `npx nx test api` to test the application
+| npx nx serve api | serve the application |
+| npx nx build api | build the application |
+| npx nx test api  | test the application  |
 
 **Add a file `apps/api/src/app/todos.ts`.**
 

docs/shared/react-tutorial/08-create-libs.md

@@ -179,7 +179,9 @@ export default App;
 
 **Restart both `npx nx serve api` and `npx nx serve todos` and you should see the application running.**
 
-> Nx helps you explore code generation options. Run `npx nx g @nrwl/react:component --help` to see all options available. Pass `--dry-run` to the command to see what would be generated without actually changing anything, like this: `npx nx g @nrwl/react:component mycmp --project=ui --dry-run`.
+{% callout type="note" title="Nx helps you" %}
+Nx helps you explore code generation options. Run `npx nx g @nrwl/react:component --help` to see all options available. Pass `--dry-run` to the command to see what would be generated without actually changing anything, like this: `npx nx g @nrwl/react:component mycmp --project=ui --dry-run`.
+{% /callout %}
 
 ## What's Next
 

docs/shared/tools-workspace-builders.md

@@ -1,4 +1,6 @@
-> In Nx 13.10+, local nx plugins can contain executors that are used in the workspace. When creating a custom executor for your workspace, look into the [nx-plugin guide](/packages/nx-plugin) to simplify the build process.
+{% callout type="check" title="Local Nx plugins" %}
+In Nx 13.10+, local nx plugins can contain executors that are used in the workspace. When creating a custom executor for your workspace, look into the [nx-plugin guide](/packages/nx-plugin) to simplify the build process.
+{% /callout %}
 
 # Creating Custom Executors
 

docs/shared/update.md

@@ -34,7 +34,9 @@ At this point, no packages have been installed, and no other files have been tou
 
 Now, you can inspect `package.json` to see if the changes make sense. Sometimes the migration can update a package to a version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments.
 
-> At this stage, after inspecting the `package.json`, you may wish to manually run the appropriate install command for your workspace (e.g. `npm install`, `yarn`, or `pnpm install`) but in the next step `nx migrate --run-migrations` will also run this automatically for you.
+{% callout type="note" title="Inspect the changes" %}
+At this stage, after inspecting the `package.json`, you may wish to manually run the appropriate install command for your workspace (e.g. `npm install`, `yarn`, or `pnpm install`) but in the next step `nx migrate --run-migrations` will also run this automatically for you.
+{% /callout %}
 
 ### Step 2: Running migrations
 

docs/shared/using-executors.md

@@ -43,7 +43,9 @@ The executors that are available for each project are defined and configured in
 
 Each project has its executors defined in the `targets` property. In this snippet, `cart` has two executors defined - `build` and `test`.
 
-> Note: `build` and `test` can be any strings you choose. For the sake of consistency, we make `test` run unit tests for every project and `build` produce compiled code for the projects which can be built.
+{% callout type="note" title="More details" %}
+`build` and `test` can be any strings you choose. For the sake of consistency, we make `test` run unit tests for every project and `build` produce compiled code for the projects which can be built.
+{% /callout %}
 
 Each executor definition has an `executor` property and, optionally, an `options` and a `configurations` property.
 
@@ -233,11 +235,13 @@ The `runExecutor` utility will find the target in the configuration, find the ex
 
 ### Devkit helper functions
 
-- `logger` -- Wraps `console` to add some formatting.
+| Property                 | Description                                                    |
-- `getPackageManagerCommand` -- Returns commands for the package manager used in the workspace.
+| ------------------------ | -------------------------------------------------------------- |
-- `parseTargetString` -- Parses a target string into {project, target, configuration}.
+| logger                   | Wraps `console` to add some formatting                         |
-- `readTargetOptions` -- Reads and combines options for a given target.
+| getPackageManagerCommand | Returns commands for the package manager used in the workspace |
-- `runExecutor` -- Constructs options and invokes an executor.
+| parseTargetString        | Parses a target string into `{project, target, configuration}` |
+| readTargetOptions        | Reads and combines options for a given target                  |
+| runExecutor              | Constructs options and invokes an executor                     |
 
 See more helper functions in the [Devkit API Docs](/devkit/index#functions)
 

docs/shared/using-nx/affected.md

@@ -1,6 +1,8 @@
 # Affected
 
-> Before reading this guide, check out the [mental model guide](/using-nx/mental-model). It will help you understand how computation caching fits into the rest of Nx.
+{% callout type="note" title="First thing!" %}
+Before reading this guide, [check out the mental model guide](/using-nx/mental-model). It will help you understand how computation caching fits into the rest of Nx.
+{% /callout %}
 
 ## Overview
 

docs/shared/using-nx/caching.md

@@ -1,6 +1,8 @@
 # Computation Caching
 
-> Before reading this guide, check out the [mental model guide](/using-nx/mental-model). It will help you understand how computation caching fits into the rest of Nx.
+{% callout type="note" title="First thing!" %}
+Before reading this guide, [check out the mental model guide](/using-nx/mental-model). It will help you understand how computation caching fits into the rest of Nx.
+{% /callout %}
 
 ## Overview
 

docs/shared/using-nx/dte.md

@@ -1,6 +1,8 @@
 # Distributed Task Execution
 
-> Before reading this guide, check out the [mental model guide](/using-nx/mental-model). It will help you understand how computation caching fits into the rest of Nx.
+{% callout type="note" title="First thing!" %}
+Before reading this guide, [check out the mental model guide](/using-nx/mental-model). It will help you understand how computation caching fits into the rest of Nx.
+{% /callout %}
 
 {% nx-cloud-section %}
 

docs/shared/using-nx/nx-cli.md

@@ -23,7 +23,9 @@ nx run my-js-app:build
 nx build my-js-app
 ```
 
-> Nx also automatically caches the output of running targets so re-running the same target on the same project source code will be instant.
+{% callout type="check" title="Nx saves you time" %}
+Nx also automatically caches the output of running targets so re-running the same target on the same project source code will be instant.
+{% /callout %}
 
 However, `nx build` is only an abstraction over what it means to "build" projects rather than tied to a certain
 implementation. For instance, if you have a `project.json` file defining `build` using
@@ -91,7 +93,9 @@ understand the architecture of the codebase.
 The [`nx graph` command](/cli/dep-graph) displays this project graph in a web browser for you to
 explore.
 
-Note: In older versions of Nx, the project graph was launched with `nx dep-graph`. For backward compatibility, that command is aliased to `nx graph`.
+{% callout type="note" title="Previously" %}
+In older versions of Nx, the project graph was launched with `nx dep-graph`. For backward compatibility, that command is aliased to `nx graph`.
+{% /callout %}
 
 ```bash
 nx graph
@@ -113,7 +117,8 @@ nx list @nrwl/react # Lists capabilities in the @nrwl/react plugin
 
 There are some environment variables that you can set to log additional information from Nx.
 
-- Setting **NX_VERBOSE_LOGGING=true** will print debug information useful for troubleshooting.
+| Property                       | Type    | Description                                                                                                                                   |
-- Setting **NX_PERF_LOGGING=true** will print debug information useful for profiling executors and Nx itself.
+| ------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-- Setting **NX_TASKS_RUNNER_DYNAMIC_OUTPUT=false** will use non-dynamic terminal output strategy (what you see in CI),
+| NX_VERBOSE_LOGGING             | boolean | If set to `true`, will print debug information useful for troubleshooting                                                                     |
-  even when you terminal can support the dynamic version.
+| NX_PERF_LOGGING                | boolean | If set to `true`, will print debug information useful for for profiling executors and Nx itself                                               |
+| NX_TASKS_RUNNER_DYNAMIC_OUTPUT | boolean | If set to `false`, will use non-dynamic terminal output strategy (what you see in CI), even when you terminal can support the dynamic version |

docs/shared/workspace/applications-and-libraries.md

@@ -14,6 +14,10 @@ Therefore, consuming libraries is very straightforward, and similar to what you
 
 Having a dedicated library project is a much stronger boundary compared to just separating code into folders, though. Each Nx library has a so-called _"public API"_, represented by an `index.ts` barrel file. This forces developers into an _"API thinking"_ of what should be exposed and thus be made available for others to consume, and what on the others side should remain private within the library itself.
 
+{% callout type="caution" title="Library !== published artefact" %}
+[This is a common misconception, moving code into libraries can be done from a pure code organization perspective](#misconception).
+{% /callout %}
+
 ## Mental model
 
 A common mental model is to **see the application as "containers"** that link, bundle and compile functionality implemented in libraries for being deployed.

docs/shared/workspace/buildable-and-publishable-libraries.md

@@ -13,7 +13,9 @@ This document will look to explain the motivations for why you would use either
 
 You might use the `--publishable` option when generating a new Nx library if your intention is to distribute it outside the monorepo.
 
-> If you are using `@nrwl/js:lib`, check out [Nx and Typescript](/getting-started/nx-and-typescript#publish-your-typescript-packages-to-npm)
+{% callout type="note" title="@nrwl/js" %}
+If you are using `@nrwl/js:lib`, check out [Nx and Typescript](/getting-started/nx-and-typescript#publish-your-typescript-packages-to-npm)
+{% /callout %}
 
 One typical scenario for this may be that you use Nx to develop your organizations UI design system component library (maybe using its Storybook integration), which should be available also to your organizations’ apps that are not hosted within the same monorepo.
 
@@ -33,6 +35,8 @@ Buildable libraries are similar to "publishable libraries" described above. Thei
 
 Buildable libraries are mostly used for producing some pre-compiled output that can be directly referenced from an Nx workspace application without the need to again compile it. A typical scenario is to leverage Nx’s [incremental building](/ci/incremental-builds) capabilities.
 
-> Note: In order for a buildable library to be pre-compiled, it can only depend on other buildable libraries. This allows you to take full advantage of incremental builds.
+{% callout type="warning" title="More details" %}
+In order for a buildable library to be pre-compiled, it can only depend on other buildable libraries. This allows you to take full advantage of incremental builds.
+{% /callout %}
 
 For more details on the mechanics, remember that Nx is an open source project, so you can see the actual impact of the generator by looking at the source code (the best starting point is probably `packages/<framework>/src/generators/library/library.ts`).

docs/shared/workspace/grouping-libraries.md

@@ -12,7 +12,9 @@ For instance, if a library under the `booking` folder is now being shared by mul
 nx g move --project booking-some-library shared/some-library
 ```
 
-> **Note**: For Angular projects, you should use the [`@nrwl/angular:move` generator](/packages/angular/generators/move) instead.
+{% callout type="note" title="Angular" %}
+For Angular projects, you should use the [`@nrwl/angular:move` generator](/packages/angular/generators/move) instead.
+{% /callout %}
 
 ## Remove Generator
 

nx-dev/ui-markdoc/src/lib/tags/callout.component.tsx

@@ -2,12 +2,12 @@ import {
   CheckCircleIcon,
   ExclamationIcon,
   InformationCircleIcon,
-  XCircleIcon,
+  HandIcon,
 } from '@heroicons/react/outline';
 import cx from 'classnames';
 import { ReactNode } from 'react';
 
-type CalloutType = 'note' | 'warning' | 'check' | 'error';
+type CalloutType = 'note' | 'warning' | 'check' | 'caution';
 const typeMap: Record<
   CalloutType,
   {
@@ -48,8 +48,8 @@ const typeMap: Record<
     titleColor: 'text-green-600',
     textColor: 'text-green-700',
   },
-  error: {
+  caution: {
-    icon: <XCircleIcon className="h-5 w-5 text-red-500" aria-hidden="true" />,
+    icon: <HandIcon className="h-5 w-5 text-red-500" aria-hidden="true" />,
     backgroundColor: 'bg-red-50',
     borderColor: 'ring-red-100',
     titleColor: 'text-red-600',
@@ -71,7 +71,7 @@ export function Callout({
   return (
     <aside
       className={cx(
-        'not-prose mb-6 rounded-md p-4 ring-1',
+        'my-6 rounded-md p-4 ring-1',
         ui.backgroundColor,
         ui.borderColor
       )}
@@ -82,7 +82,7 @@ export function Callout({
           <h5 className={cx('mt-0 text-sm font-medium', ui.titleColor)}>
             {title}
           </h5>
-          <div className={cx('mt-2 text-sm', ui.textColor)}>{children}</div>
+          <div className={cx('prose-sm mt-2', ui.textColor)}>{children}</div>
         </div>
       </div>
     </aside>

nx-dev/ui-markdoc/src/lib/tags/nx-cloud-section.component.tsx

@@ -24,9 +24,7 @@ export function NxCloudSection({ children }: { children: ReactNode }) {
               />
             </svg>
           </span>
-          <p className="ml-4 flex text-base">
+          <p className="ml-4 flex text-base">This section is about Nx Cloud.</p>
-            This section is about Nx Cloud specifically.
-          </p>
         </div>
         <div className="order-3 mt-2 w-full flex-shrink-0 sm:order-2 sm:mt-0 sm:w-auto">
           <a

nx-dev/ui-markdoc/src/lib/tags/tabs.component.tsx

@@ -16,7 +16,7 @@ export function Tabs({
   return (
     <TabContext.Provider value={currentTab}>
       <section className="mb-8 py-4">
-        <div className="not-prose hidden sm:block">
+        <div className="not-prose ">
           <div className="border-b border-gray-100">
             <nav className="-mb-px flex space-x-8" aria-label="Tabs">
               {labels.map((label: string) => (