docs(nxdev): improve markdown capabilities (nrwl#10965)

docs/generated/packages/storybook.json

@@ -34,7 +34,7 @@
       "id": "migrate-webpack-final-react",
       "name": "Migrate to the Nrwl React Storybook Preset",
       "file": "shared/guides/storybook/migrate-webpack-final-react",
-      "content": "# Nrwl React Storybook Preset\n\nNx 12.7 comes with a dedicated Storybook preset for React which drammatically simplifies the Storybook setup and makes sure that Storybook uses the same webpack configuration as your React applications running within an Nx workspace.\n\n<iframe loading=\"lazy\" width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/oUE74McS_NY\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen\"></iframe>\n\nHere are the main differences to the previous versions of Nx:\n\n- there's no `webpack.config.js`; Custom webpack configurations can be added in the `webpackFinal` property of the `main.js` file\n- the `main.js` file now contains a predefined Storybook preset exported by `@nrwl/react/plugins/storybook`.\n\nHere's an example of a newly generated `main.js` file:\n\n```javascript\n// project-level .storybook/main.js file\nconst rootMain = require('../../../.storybook/main');\n\nmodule.exports = {\n  ...rootMain,\n\n  core: {\n    ...rootMain.core,\n    // opt-into Storybook Webpack 5\n    builder: 'webpack5'\n  }\n\n  stories: [\n    ...rootMain.stories,\n    '../src/lib/**/*.stories.mdx',\n    '../src/lib/**/*.stories.@(js|jsx|ts|tsx)',\n  ],\n  addons: [...rootMain.addons, '@nrwl/react/plugins/storybook'],\n  webpackFinal: async (config, { configType }) => {\n    // apply any global webpack configs that might have been specified in .storybook/main.js\n    if (rootMain.webpackFinal) {\n      config = await rootMain.webpackFinal(config, { configType });\n    }\n\n    // add your own webpack tweaks if needed\n\n    return config;\n  },\n};\n```\n\nAt the Nx workspace root level, the configuration file looks as follows:\n\n```javascript\n// root level .storybook/main.js file\nmodule.exports = {\n  stories: [],\n  addons: ['@storybook/addon-essentials'],\n  // uncomment the property below if you want to apply some webpack config globally\n  // webpackFinal: async (config, { configType }) => {\n  //   // Make whatever fine-grained changes you need that should apply to all storybook configs\n\n  //   // Return the altered config\n  //   return config;\n  // },\n};\n```\n\n## Migrating\n\nIf you're upgrading from a lower version of Nx, your old Storybook configuration will still work. New configurations generated will use the new syntax as shown above. The newly generated code will also make sure to extend from a global `webpack.config.js` which might exist in the root-level `.storybook/` directory of your Nx workspace.\n\nThis gives you the flexibility to incrementally migrate your configurations.\n\nHere's the step-by-step migration process:\n\n### 1. adjust the `main.js` file\n\nRestructure your `main.js` file so that it looks like in the example illustrated above.\n\nIf you need to keep your root-level `.storybook/webpack.config.js` for now, then make sure you adjust the `main.js` in a way that it properly calls the root-level `webpack.config.js` to inherit all of the global configurations.\n\n```javascript\nconst rootMain = require('../../../.storybook/main');\nconst rootWebpackConfig = require('../../../.storybook/webpack.config');\n\nmodule.exports = {\n  ...rootMain,\n  ...\n  webpackFinal: async (config) => {\n    // for backwards compatibility call the `rootWebpackConfig`\n    // this can be removed once that one is migrated fully to\n    // use the `webpackFinal` property in the `main.js` file\n    config = rootWebpackConfig({ config });\n\n    // add your own webpack tweaks if needed\n\n    return config;\n  },\n};\n```\n\n**Note:** The easiest way is probably to generate a new library and Storybook configuration and then copy & paste the `main.js`.\n\n### 2. Move any custom webpack configuration to `webpackFinal`\n\nIn previous versions of Nx a custom `webpack.config.js` was generated with the following content:\n\n```javascript\nmodule.exports = async ({ config, mode }) => {\n  config = await rootWebpackConfig({ config, mode });\n\n  const tsPaths = new TsconfigPathsPlugin({\n    configFile: './tsconfig.base.json',\n  });\n\n  config.resolve.plugins\n    ? config.resolve.plugins.push(tsPaths)\n    : (config.resolve.plugins = [tsPaths]);\n\n  // Found this here: https://github.com/nrwl/nx/issues/2859\n  // And copied the part of the solution that made it work\n\n  const svgRuleIndex = config.module.rules.findIndex((rule) => {\n    const { test } = rule;\n\n    return test.toString().startsWith('/\\\\.(svg|ico');\n  });\n  config.module.rules[svgRuleIndex].test =\n    /\\.(ico|jpg|jpeg|png|gif|eot|otf|webp|ttf|woff|woff2|cur|ani|pdf)(\\?.*)?$/;\n\n  config.module.rules.push(\n    {\n      test: /\\.(png|jpe?g|gif|webp)$/,\n      loader: require.resolve('url-loader'),\n      options: {\n        limit: 10000, // 10kB\n        name: '[name].[hash:7].[ext]',\n      },\n    },\n    {\n      test: /\\.svg$/,\n      oneOf: [\n        // If coming from JS/TS file, then transform into React component using SVGR.\n        {\n          issuer: {\n            test: /\\.[jt]sx?$/,\n          },\n          use: [\n            {\n              loader: require.resolve('@svgr/webpack'),\n              options: {\n                svgo: false,\n                titleProp: true,\n                ref: true,\n              },\n            },\n            {\n              loader: require.resolve('url-loader'),\n              options: {\n                limit: 10000, // 10kB\n                name: '[name].[hash:7].[ext]',\n                esModule: false,\n              },\n            },\n          ],\n        },\n        // Fallback to plain URL loader.\n        {\n          use: [\n            {\n              loader: require.resolve('url-loader'),\n              options: {\n                limit: 10000, // 10kB\n                name: '[name].[hash:7].[ext]',\n              },\n            },\n          ],\n        },\n      ],\n    }\n  );\n\n  return config;\n};\n```\n\nSuch webpack file is no more needed as the `@nrwl/react/plugins/storybook` now takes care of it.\n\nIn case you made custom modifications to the `webpack.config.js` file, you need to move them over to the `main.js` `webpackFinal` property and then delete the `webpack.config.js`.\n\n### 3. Remove the root-level `.storybook/webpack.config.js` file\n\nOnce you've migrated all your libraries, you can think about removing the root-level `.storybook/webpack.config.js` file and migrate any custom configuration there to `.storybook/main.js` `webpackFinal` property in the very same folder.\n\n### 4. Opting in to Webpack 5\n\nIf you choose to opt-in to Webpack 5, by specifying `builder: 'webpack5'` in your project's `.storybook/main.(js|ts)` (as shown above, in the example of a newly generated `main.js` file), don't forget to add the Storybook dependencies for Webpack 5 to work:\n\n```shell\nyarn add -D @storybook/builder-webpack5 @storybook/manager-webpack5\n```\n\nor if you're using `npm`:\n\n```shell\nnpm install --save-dev @storybook/builder-webpack5 @storybook/manager-webpack5\n```\n"
+      "content": "# Nrwl React Storybook Preset\n\nNx 12.7 comes with a dedicated Storybook preset for React which drammatically simplifies the Storybook setup and makes sure that Storybook uses the same webpack configuration as your React applications running within an Nx workspace.\n\n{% youtube\nsrc=\"https://www.youtube.com/embed/oUE74McS_NY\"\ntitle=\"New in Nx 12.7: React Storybook Preset\"\nwidth=\"100%\" /%}\n\nHere are the main differences to the previous versions of Nx:\n\n- there's no `webpack.config.js`; Custom webpack configurations can be added in the `webpackFinal` property of the `main.js` file\n- the `main.js` file now contains a predefined Storybook preset exported by `@nrwl/react/plugins/storybook`.\n\nHere's an example of a newly generated `main.js` file:\n\n```javascript\n// project-level .storybook/main.js file\nconst rootMain = require('../../../.storybook/main');\n\nmodule.exports = {\n  ...rootMain,\n\n  core: {\n    ...rootMain.core,\n    // opt-into Storybook Webpack 5\n    builder: 'webpack5'\n  }\n\n  stories: [\n    ...rootMain.stories,\n    '../src/lib/**/*.stories.mdx',\n    '../src/lib/**/*.stories.@(js|jsx|ts|tsx)',\n  ],\n  addons: [...rootMain.addons, '@nrwl/react/plugins/storybook'],\n  webpackFinal: async (config, { configType }) => {\n    // apply any global webpack configs that might have been specified in .storybook/main.js\n    if (rootMain.webpackFinal) {\n      config = await rootMain.webpackFinal(config, { configType });\n    }\n\n    // add your own webpack tweaks if needed\n\n    return config;\n  },\n};\n```\n\nAt the Nx workspace root level, the configuration file looks as follows:\n\n```javascript\n// root level .storybook/main.js file\nmodule.exports = {\n  stories: [],\n  addons: ['@storybook/addon-essentials'],\n  // uncomment the property below if you want to apply some webpack config globally\n  // webpackFinal: async (config, { configType }) => {\n  //   // Make whatever fine-grained changes you need that should apply to all storybook configs\n\n  //   // Return the altered config\n  //   return config;\n  // },\n};\n```\n\n## Migrating\n\nIf you're upgrading from a lower version of Nx, your old Storybook configuration will still work. New configurations generated will use the new syntax as shown above. The newly generated code will also make sure to extend from a global `webpack.config.js` which might exist in the root-level `.storybook/` directory of your Nx workspace.\n\nThis gives you the flexibility to incrementally migrate your configurations.\n\nHere's the step-by-step migration process:\n\n### 1. adjust the `main.js` file\n\nRestructure your `main.js` file so that it looks like in the example illustrated above.\n\nIf you need to keep your root-level `.storybook/webpack.config.js` for now, then make sure you adjust the `main.js` in a way that it properly calls the root-level `webpack.config.js` to inherit all of the global configurations.\n\n```javascript\nconst rootMain = require('../../../.storybook/main');\nconst rootWebpackConfig = require('../../../.storybook/webpack.config');\n\nmodule.exports = {\n  ...rootMain,\n  ...\n  webpackFinal: async (config) => {\n    // for backwards compatibility call the `rootWebpackConfig`\n    // this can be removed once that one is migrated fully to\n    // use the `webpackFinal` property in the `main.js` file\n    config = rootWebpackConfig({ config });\n\n    // add your own webpack tweaks if needed\n\n    return config;\n  },\n};\n```\n\n**Note:** The easiest way is probably to generate a new library and Storybook configuration and then copy & paste the `main.js`.\n\n### 2. Move any custom webpack configuration to `webpackFinal`\n\nIn previous versions of Nx a custom `webpack.config.js` was generated with the following content:\n\n```javascript\nmodule.exports = async ({ config, mode }) => {\n  config = await rootWebpackConfig({ config, mode });\n\n  const tsPaths = new TsconfigPathsPlugin({\n    configFile: './tsconfig.base.json',\n  });\n\n  config.resolve.plugins\n    ? config.resolve.plugins.push(tsPaths)\n    : (config.resolve.plugins = [tsPaths]);\n\n  // Found this here: https://github.com/nrwl/nx/issues/2859\n  // And copied the part of the solution that made it work\n\n  const svgRuleIndex = config.module.rules.findIndex((rule) => {\n    const { test } = rule;\n\n    return test.toString().startsWith('/\\\\.(svg|ico');\n  });\n  config.module.rules[svgRuleIndex].test =\n    /\\.(ico|jpg|jpeg|png|gif|eot|otf|webp|ttf|woff|woff2|cur|ani|pdf)(\\?.*)?$/;\n\n  config.module.rules.push(\n    {\n      test: /\\.(png|jpe?g|gif|webp)$/,\n      loader: require.resolve('url-loader'),\n      options: {\n        limit: 10000, // 10kB\n        name: '[name].[hash:7].[ext]',\n      },\n    },\n    {\n      test: /\\.svg$/,\n      oneOf: [\n        // If coming from JS/TS file, then transform into React component using SVGR.\n        {\n          issuer: {\n            test: /\\.[jt]sx?$/,\n          },\n          use: [\n            {\n              loader: require.resolve('@svgr/webpack'),\n              options: {\n                svgo: false,\n                titleProp: true,\n                ref: true,\n              },\n            },\n            {\n              loader: require.resolve('url-loader'),\n              options: {\n                limit: 10000, // 10kB\n                name: '[name].[hash:7].[ext]',\n                esModule: false,\n              },\n            },\n          ],\n        },\n        // Fallback to plain URL loader.\n        {\n          use: [\n            {\n              loader: require.resolve('url-loader'),\n              options: {\n                limit: 10000, // 10kB\n                name: '[name].[hash:7].[ext]',\n              },\n            },\n          ],\n        },\n      ],\n    }\n  );\n\n  return config;\n};\n```\n\nSuch webpack file is no more needed as the `@nrwl/react/plugins/storybook` now takes care of it.\n\nIn case you made custom modifications to the `webpack.config.js` file, you need to move them over to the `main.js` `webpackFinal` property and then delete the `webpack.config.js`.\n\n### 3. Remove the root-level `.storybook/webpack.config.js` file\n\nOnce you've migrated all your libraries, you can think about removing the root-level `.storybook/webpack.config.js` file and migrate any custom configuration there to `.storybook/main.js` `webpackFinal` property in the very same folder.\n\n### 4. Opting in to Webpack 5\n\nIf you choose to opt-in to Webpack 5, by specifying `builder: 'webpack5'` in your project's `.storybook/main.(js|ts)` (as shown above, in the example of a newly generated `main.js` file), don't forget to add the Storybook dependencies for Webpack 5 to work:\n\n```shell\nyarn add -D @storybook/builder-webpack5 @storybook/manager-webpack5\n```\n\nor if you're using `npm`:\n\n```shell\nnpm install --save-dev @storybook/builder-webpack5 @storybook/manager-webpack5\n```\n"
     },
     {
       "id": "migrate-webpack-final-angular",

docs/nx-cloud/intro/nx-cloud.md

@@ -14,8 +14,14 @@ Most developers will benefit from Nx Cloud without ever changing any of their wo
 
 The [top level organization page](https://nx.app/orgs/5e38af6de037b5000598b2d6/workspaces/5edaf12087863a0005781f17) displays recent runs and a helpful dashboard of information about commands run in the repository.
 
-<iframe src="https://nx.app/orgs/5e38af6de037b5000598b2d6/workspaces/5edaf12087863a0005781f17?hideHeader=true"></iframe>
+{% iframe
+src="https://nx.app/orgs/5e38af6de037b5000598b2d6/workspaces/5edaf12087863a0005781f17?hideHeader=true"
+title="Nx Cloud dashboard"
+width="100%" /%}
 
 Each branch in the repository has its own [dedicated page](https://nx.app/branch?workspaceId=5edaf12087863a0005781f17&branchName=master) where you can view agent utilization and a waterfall task execution graph for the most recent runs against that branch.
 
-<iframe src="https://nx.app/branch?workspaceId=5edaf12087863a0005781f17&branchName=master&hideHeader=true"></iframe>
+{% iframe
+src="https://nx.app/branch?workspaceId=5edaf12087863a0005781f17&branchName=master&hideHeader=true"
+title="Nx Cloud branch view"
+width="100%" /%}

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

@@ -1,6 +1,9 @@
 # Angular Nx Tutorial - Step 1: Create Application
 
-<iframe loading="lazy" width="560" height="315" src="https://www.youtube.com/embed/i37yJKK8qGI" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+{% youtube
+src="https://www.youtube.com/embed/i37yJKK8qGI"
+title="Nx.dev Tutorial | Angular | Step 1: Create Application"
+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.
 

docs/shared/angular-tutorial/02-add-e2e-test.md

@@ -1,6 +1,9 @@
 # Angular Nx Tutorial - Step 2: Add E2E Tests
 
-<iframe loading="lazy" width="560" height="315" src="https://www.youtube.com/embed/owRAO75DIR4" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+{% youtube
+src="https://www.youtube.com/embed/owRAO75DIR4"
+title="Nx.dev Tutorial | Angular | Step 2: Add E2E Test"
+width="100%" /%}
 
 By default, Nx uses [Cypress](/cypress/overview) to run E2E tests.
 

docs/shared/angular-tutorial/03-display-todos.md

@@ -1,6 +1,9 @@
 # Angular Nx Tutorial - Step 3: Display Todos
 
-<iframe loading="lazy" width="560" height="315" src="https://www.youtube.com/embed/JlKAwGXmpac" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+{% youtube
+src="https://www.youtube.com/embed/JlKAwGXmpac"
+title="Nx.dev Tutorial | Angular | Step 3: Display Todos"
+width="100%" /%}
 
 Great! You have a failing E2E test. Now you can make it pass!
 

docs/shared/angular-tutorial/04-connect-to-api.md

@@ -1,6 +1,9 @@
 # Angular Nx Tutorial - Step 4: Connect to an API
 
-<iframe loading="lazy" width="560" height="315" src="https://www.youtube.com/embed/digMpZzPtg8" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+{% youtube
+src="https://www.youtube.com/embed/JlKAwGXmpac"
+title="Nx.dev Tutorial | Angular | Step 4: Connect to API"
+width="100%" /%}
 
 Real-world applications do not live in isolation — they need APIs to talk to. Setup your app to talk to an API.
 

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

@@ -1,6 +1,9 @@
 # Angular Nx Tutorial - Step 5: Add Node Application Implementing an API
 
-<iframe loading="lazy" width="560" height="315" src="https://www.youtube.com/embed/SsCx2WErVTI" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+{% youtube
+src="https://www.youtube.com/embed/SsCx2WErVTI"
+title="Nx.dev Tutorial | Angular | Step 5: Add Node Application Implementing API"
+width="100%" /%}
 
 The requests fail because the API has not been created yet. Using Nx you can develop node applications next to your Angular applications. You can use same commands to run and test them. You can share code between the backend and the frontend. Use this capability to implement the API service.
 

docs/shared/angular-tutorial/06-proxy.md

@@ -1,6 +1,9 @@
 # Angular Nx Tutorial - Step 6: Proxy
 
-<iframe loading="lazy" width="560" height="315" src="https://www.youtube.com/embed/7d6jDAbmVnE" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+{% youtube
+src="https://www.youtube.com/embed/7d6jDAbmVnE"
+title="Nx.dev Tutorial | Angular | Step 6: Configure Proxy"
+width="100%" /%}
 
 You passed `--frontendProject=todos` when creating the node application. What did that argument do?
 

docs/shared/angular-tutorial/07-share-code.md

@@ -1,6 +1,9 @@
 # Angular Nx Tutorial - Step 7: Share Code
 
-<iframe loading="lazy" width="560" height="315" src="https://www.youtube.com/embed/icyOSQ6gAm0" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+{% youtube
+src="https://www.youtube.com/embed/icyOSQ6gAm0"
+title="Nx.dev Tutorial | Angular | Step 7: Share Code"
+width="100%" /%}
 
 Awesome! The application is working end to end! However, there is a problem. Both the backend and the frontend define the `Todo` interface. The interface is in sync now, but in a real application, over time, it will diverge, and, as a result, runtime errors will creep in. You should share this interface between the backend and the frontend. In Nx, you can do this by creating a library.