docs: warning callouts on outdated pages (#1163)

## 🧰 Changes

adds temporary "this is outdated" callouts to the pages we sync to our
guides, and moves those pages into their own respective `legacy/`
directory.

we'll add new docs to backfill this info (ideally with better separation
of concerns) sometime in the not-too-distant future.

.github/workflows/docs.yml

@@ -46,4 +46,4 @@ jobs:
       - name: Sync docs to ReadMe
         uses: readmeio/rdme@v9
         with:
-          rdme: docs ./documentation --key=${{ secrets.README_DEVELOPERS_API_KEY }} --version=${{ vars.README_DEVELOPERS_MAIN_VERSION }}
+          rdme: docs ./documentation/legacy/ --key=${{ secrets.README_DEVELOPERS_API_KEY }} --version=${{ vars.README_DEVELOPERS_MAIN_VERSION }}

documentation/github-actions-docs-example.md → documentation/legacy/github-actions-docs-example.md

@@ -16,6 +16,12 @@ Check out `.github/workflows/docs.yml` for more info on this!
 
 -->
 
+> 🚧 Deprecated Guidance
+>
+> This example is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [[email protected]](mailto:[email protected])
+>
+> We will be updating this document with our latest guidance soon. Thanks for your patience!
+
 Do you have Markdown files stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync them to ReadMe every time they're updated in GitHub. Let's go over how to set this up!
 
 ## "Automagical" Workflow File Generation

documentation/github-actions-openapi-example.md → documentation/legacy/github-actions-openapi-example.md

@@ -15,6 +15,12 @@ Check out `.github/workflows/docs.yml` for more info on this!
 
 -->
 
+> 🚧 Deprecated Guidance
+>
+> This example is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [[email protected]](mailto:[email protected])
+>
+> We will be updating this document with our latest guidance soon. Thanks for your patience!
+
 Is your OpenAPI definition stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync it to ReadMe every time it's updated in GitHub. Let's go over how to set this up!
 
 ## "Automagical" Workflow File Generation

documentation/rdme.md → documentation/legacy/rdme.md

@@ -47,6 +47,12 @@ To see detailed CLI setup instructions and all available commands, check out [th
 
 ### Markdown File Setup
 
+> 🚧 Deprecated Guidance
+>
+> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [[email protected]](mailto:[email protected])
+>
+> We will be updating this document with our latest guidance soon. Thanks for your patience!
+
 > 📘 Guides, Changelog, Custom Pages... you name it!
 >
 > The following guidance on Markdown file setup is nearly identical for Guides (i.e. the `docs` command), Changelog (i.e. the `changelogs` command), and Custom Pages (i.e. the `custompages` command). There are a couple of small differences:
@@ -131,14 +137,20 @@ While there are [dozens of event options available](https://docs.github.com/acti
 
 ### Quick Start
 
+> 🚧 Deprecated Guidance
+>
+> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [[email protected]](mailto:[email protected])
+>
+> We will be updating this document with our latest guidance soon. Thanks for your patience!
+
 The fastest way to create a GitHub Actions workflow file is by doing the following:
 
 1. Download `rdme` to your local machine (see [our setup instructions](https://github.com/readmeio/rdme#setup))
 2. Open your command line at the root of your GitHub repository
 3. Run the command you wish to automate on your local machine with the `--github` flag tacked on at the end. For example:
 
 ```sh
-rdme openapi --github
+rdme openapi validate --github
 ```
 
 This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you. 🪄
@@ -164,7 +176,7 @@ To use sensitive information (like your ReadMe API key) in your `rdme` GitHub Ac
 ```yml
 - uses: readmeio/rdme@RDME_VERSION
   with:
-    rdme: openapi [url-or-local-path-to-file] --key=${{ secrets.README_API_KEY }} --id=API_DEFINITION_ID
+    rdme: openapi validate [url-or-local-path-to-file] --key=${{ secrets.README_API_KEY }} --id=API_DEFINITION_ID
 ```
 
 ### Manually Configuring a GitHub Actions Workflow
@@ -205,6 +217,12 @@ The following section has links to full GitHub Actions workflow file examples.
 
 ### GitHub Actions Examples
 
+> 🚧 Deprecated Guidance
+>
+> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [[email protected]](mailto:[email protected])
+>
+> We will be updating this document with our latest guidance soon. Thanks for your patience!
+
 Want to start syncing? We have several example workflow files available:
 
 - [Syncing an OpenAPI definition](https://docs.readme.com/docs/github-actions-openapi-example)
@@ -229,7 +247,7 @@ pipelines:
   default:
     - step:
         script:
-          - npx rdme@RDME_VERSION openapi [url-or-local-path-to-file] --key=$README_API_KEY --id=API_DEFINITION_ID
+          - npx rdme@RDME_VERSION openapi validate [url-or-local-path-to-file] --key=$README_API_KEY --id=API_DEFINITION_ID
 ```
 ```yml CircleCI (.circleci/config.yml)
 version: 2.1
@@ -241,7 +259,7 @@ jobs:
       - image: node:NODE_VERSION
     steps:
       - run:
-          command: npx rdme@RDME_VERSION openapi [url-or-local-path-to-file] --key=$README_API_KEY --id=API_DEFINITION_ID
+          command: npx rdme@RDME_VERSION openapi validate [url-or-local-path-to-file] --key=$README_API_KEY --id=API_DEFINITION_ID
 ```
 ```yml GitLab CI (rdme-sync.gitlab-ci.yml)
 # Official framework image. Look for the different tagged releases at:
@@ -250,15 +268,15 @@ image: node:NODE_VERSION
 
 sync-via-rdme:
   script:
-    - npx rdme@RDME_VERSION openapi [url-or-local-path-to-file] --key=$README_API_KEY --id=API_DEFINITION_ID
+    - npx rdme@RDME_VERSION openapi validate [url-or-local-path-to-file] --key=$README_API_KEY --id=API_DEFINITION_ID
 ```
 ```yml Travis CI (.travis.yml)
 # https://docs.travis-ci.com/user/languages/javascript-with-nodejs/#specifying-nodejs-versions
 language: node_js
 node_js:
   - NODE_VERSION
 
-script: npx rdme@RDME_VERSION openapi [url-or-local-path-to-file] --key=$README_API_KEY --id=API_DEFINITION_ID
+script: npx rdme@RDME_VERSION openapi validate [url-or-local-path-to-file] --key=$README_API_KEY --id=API_DEFINITION_ID
 ```
 <!-- prettier-ignore-end -->
 
@@ -284,7 +302,7 @@ If you're working with the `docs` command specifically, we recommend using [dry
 If you're troubleshooting issues with the CLI (or in some non-GitHub Actions environment), you can use the `DEBUG` environmental variable to print helpful debugging info to the console:
 
 ```sh
-DEBUG=rdme* rdme openapi [url-or-local-path-to-file]
+DEBUG=rdme* rdme openapi validate [url-or-local-path-to-file]
 ```
 
 Note that this should only be used for development/debugging purposes and should not be enabled in production environments.