From 4f59f0782e7af8b5414994848abe6adb18f509f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= <slorber@users.noreply.github.com>
Date: Fri, 3 Sep 2021 19:34:10 +0200
Subject: [PATCH] docs: mention Netlify ignore build setting (#5486)

* mention Netlify ignore build setting

* doc backport
---
 website/docs/deployment.mdx                   | 19 +++++++++++++++++++
 .../version-2.0.0-beta.5/deployment.mdx       | 19 +++++++++++++++++++
 .../version-2.0.0-beta.6/deployment.mdx       | 19 +++++++++++++++++++
 3 files changed, 57 insertions(+)

diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx
index 9400cf6a80..504d657ee5 100644
--- a/website/docs/deployment.mdx
+++ b/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.
diff --git a/website/versioned_docs/version-2.0.0-beta.5/deployment.mdx b/website/versioned_docs/version-2.0.0-beta.5/deployment.mdx
index 9400cf6a80..504d657ee5 100644
--- a/website/versioned_docs/version-2.0.0-beta.5/deployment.mdx
+++ b/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.
diff --git a/website/versioned_docs/version-2.0.0-beta.6/deployment.mdx b/website/versioned_docs/version-2.0.0-beta.6/deployment.mdx
index 9400cf6a80..504d657ee5 100644
--- a/website/versioned_docs/version-2.0.0-beta.6/deployment.mdx
+++ b/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.