docs: mention Netlify ignore build setting (#5486)

* mention Netlify ignore build setting

* doc backport

website/docs/deployment.mdx

@@ -396,6 +396,25 @@ If you did not configure these build options, you may still go to "Site settings
 
 Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `main`.
 
+:::caution
+
+Some Docusaurus sites put the `docs` folder outside of `website` (most likely former Docusaurus v1 sites):
+
+```bash
+repo           # git root
+├── docs       # md files
+└── website    # docusaurus root
+```
+
+If you decide to use the `website` folder as Netlify's base directory, Netlify will not trigger builds when you update the `docs` folder, and you need to configure a [custom `ignore` command](https://docs.netlify.com/configure-builds/common-configurations/ignore-builds/):
+
+```toml title="website/netlify.toml"
+[build]
+  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/"
+```
+
+:::
+
 :::warning
 
 By default, Netlify adds trailing slashes to Docusaurus URLs.

website/versioned_docs/version-2.0.0-beta.5/deployment.mdx

@@ -396,6 +396,25 @@ If you did not configure these build options, you may still go to "Site settings
 
 Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `main`.
 
+:::caution
+
+Some Docusaurus sites put the `docs` folder outside of `website` (most likely former Docusaurus v1 sites):
+
+```bash
+repo           # git root
+├── docs       # md files
+└── website    # docusaurus root
+```
+
+If you decide to use the `website` folder as Netlify's base directory, Netlify will not trigger builds when you update the `docs` folder, and you need to configure a [custom `ignore` command](https://docs.netlify.com/configure-builds/common-configurations/ignore-builds/):
+
+```toml title="website/netlify.toml"
+[build]
+  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/"
+```
+
+:::
+
 :::warning
 
 By default, Netlify adds trailing slashes to Docusaurus URLs.

website/versioned_docs/version-2.0.0-beta.6/deployment.mdx

@@ -396,6 +396,25 @@ If you did not configure these build options, you may still go to "Site settings
 
 Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to `main`.
 
+:::caution
+
+Some Docusaurus sites put the `docs` folder outside of `website` (most likely former Docusaurus v1 sites):
+
+```bash
+repo           # git root
+├── docs       # md files
+└── website    # docusaurus root
+```
+
+If you decide to use the `website` folder as Netlify's base directory, Netlify will not trigger builds when you update the `docs` folder, and you need to configure a [custom `ignore` command](https://docs.netlify.com/configure-builds/common-configurations/ignore-builds/):
+
+```toml title="website/netlify.toml"
+[build]
+  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/"
+```
+
+:::
+
 :::warning
 
 By default, Netlify adds trailing slashes to Docusaurus URLs.