feat(cli): docusaurus deploy should support a --target-dir option

[SandPod]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

The deploy script makes a hard assumption that the remote repository only stores Docusaurus files.

In our case we have a CNAME file in the root of the repo and therefore have placed all Docusaurus files in a docs folder. Therefore, we cannot utilize this scripts since we can't specify the target directory.

This PR adds a CLI option to specify the target directory and ensures that one the target directory is cleared out while the rest of the repo is left intact.

Guide for reviewer

This is an initial attempt to see if it is something that is worth finalizing and goes in the direction the maintainers of the project would like to see.

The PR is best reviewed commit by commit where each commit attempts to apply a single change. Hopefully this can help clarify if I have misunderstood how things should be implemented.

Test Plan

Would have loved to have #7714 merged for automatic validation of these changes.

Failing a snapshot test right now, I'm not a Javascript native developer and don't feel comfortable updating snapshots without understanding the implication.

The test that is currently failing should fail since I have actually added a new prop.

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

Related issues/PRs

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	bd66946
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/66213d4a66d13f0009c31706
😎 Deploy Preview	https://deploy-preview-9767--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 54	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟠 57	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 76	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 70	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 57	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 68	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 77	🟢 100	🟢 100	🟢 90	🟠 88	Report

[slorber]

Thanks, LGTM. I simplified your implementation but overall keep the intent.

I confirm I can run:

yarn build:website:fast
yarn workspace website deploy --skip-build
yarn workspace website deploy --skip-build --target-dir subdir

Then the build folder is deployed at the gh-branch root:

https://github.com/facebook/docusaurus/tree/gh-pages

And then also to the subdir, without erasing what's at the root:

https://github.com/facebook/docusaurus/tree/gh-pages/subdir

So, it works as intended, even though we don't have great test coverage for this feature 😅