docs(v9/docs): migration guide + deprecation notice updates

README.md

@@ -20,7 +20,7 @@ With `rdme`, you can manage your API definition (we support [OpenAPI](https://sp
 Not using ReadMe for your docs? No worries. `rdme` has a variety of tools to help you identify issues with your API definition — no ReadMe account required.
 
 > [!WARNING]
-> If you're using the [new ReadMe Refactored experience](https://docs.readme.com/main/docs/welcome-to-readme-refactored), you'll want to use `rdme@10` instead. Head over to [our migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) for more information.
+> If you're using the [new ReadMe Refactored experience](https://docs.readme.com/main/docs/migration), you'll want to use `rdme@10` instead. Head over to [our migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) for more information.
 
 # Table of Contents
 

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

@@ -19,7 +19,7 @@ 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]).
+> This example is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), 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!
 

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

@@ -18,7 +18,7 @@ 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]).
+> This example is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), 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!
 

documentation/legacy/rdme.md

@@ -47,7 +47,7 @@ With `rdme`, you can create workflows for a variety of use cases, including:
 
 > 🚧 Heads up!
 >
-> Our [new ReadMe Refactored experience](https://docs.readme.com/main/docs/welcome-to-readme-refactored) doesn’t yet support `rdme`. If your project is using the new ReadMe Refactored experience, we recommend [enabling bi-directional syncing via Git](https://docs.readme.com/main/docs/bi-directional-sync) for an even better editing experience for the technical and non-technical users on your team!
+> Our [new ReadMe Refactored experience](https://docs.readme.com/main/docs/migration) doesn’t yet support `rdme`. If your project is using the new ReadMe Refactored experience, we recommend [enabling bi-directional syncing via Git](https://docs.readme.com/main/docs/bi-directional-sync) for an even better editing experience for the technical and non-technical users on your team!
 
 ## General Setup and Usage
 
@@ -57,7 +57,7 @@ To see detailed CLI setup instructions and all available commands, check out [th
 
 > 🚧 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]).
+> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), 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!
 
@@ -147,7 +147,7 @@ While there are [dozens of event options available](https://docs.github.com/acti
 
 > 🚧 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]).
+> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), 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!
 
@@ -227,7 +227,7 @@ The following section has links to full GitHub Actions workflow file 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]).
+> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), 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!
 

documentation/migration-guide.md

@@ -1,8 +1,8 @@
 # Migration Guide
 
-This guide helps you migrate your ReadMe CLI (`rdme`) setup to the latest version and prepare for future versions. Choose your migration path based on whether you're using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).
+This guide helps you migrate your ReadMe CLI (`rdme`) setup to the latest version and prepare for future versions. Choose your migration path based on whether you're using [ReadMe Refactored](https://docs.readme.com/main/docs/migration).
 
-1. If your project is using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), [use `rdme@v10`](#migrating-to-rdme10) and beyond.
+1. If your project is using [ReadMe Refactored](https://docs.readme.com/main/docs/migration), [use `rdme@v10`](#migrating-to-rdme10) and beyond.
 2. If your project is **not** yet using ReadMe Refactored, [use `rdme@v9`](#migrating-to-rdme9). The `v9` channel will continue to be maintained while we focus on making sure that everybody can upgrade their ReadMe projects to ReadMe Refactored.
 
 ## Table of Contents
@@ -34,114 +34,24 @@ npx markdown-toc documentation/migration-guide.md --maxdepth 2 --bullets="-" -i
 
 ## Migrating to `rdme@9`
 
-### Overview
-
-This release adds a few features that make it even easier to get started with `rdme`:
-
-1. **Enhanced Command Documentation**
-
-   - Complete command reference in [the `documentation/commands` directory](https://github.com/readmeio/rdme/tree/v9/documentation/commands)
-   - Detailed usage examples and parameter descriptions
-   - Structured by command category for intuitive navigation
-
-2. **Improved CLI Experience**
-
-   - Overhauled help screens with detailed examples to improve readability and ease of use
-   - Set up CLI autocompletions with [the `autocomplete` command](https://github.com/readmeio/rdme/tree/v9/documentation/commands/autocomplete.md)
-   - Smart command discovery that helps catch and correct typos
-   - Redesigned error messages with clear resolution steps
-
 <!-- prettier-ignore-start -->
 > [!NOTE]
-> `rdme@9` only works with ReadMe projects that are **not** using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). If you are using ReadMe Refactored, [you'll want to use `rdme@10`](#migrating-to-rdme10).
+> If you have **not** yet migrated ReadMe Refactored, you'll want to use this version, `v9`! The `v9` migration guide can be found [here](https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9).
 <!-- prettier-ignore-end -->
 
-### Upgrading to `v9`
-
-#### Step 1: Upgrade via `npm`
-
-To install this version of the `rdme` CLI globally, run the following command:
-
-```sh
-npm install -g rdme@9
-```
-
-More installation options can be found in [our docs](https://github.com/readmeio/rdme/tree/v9?tab=readme-ov-file#setup).
-
-#### Step 2: Update GitHub Actions Workflow
-
-If you're using the `rdme` GitHub Action, update your GitHub Actions workflow file so your `rdme` usage uses the `v9` reference like so:
-
-```yaml
-- uses: readmeio/rdme@v9
-  with:
-    rdme: openapi validate petstore.json
-```
-
-#### Step 3: Address `v9` Breaking Changes
-
-1. **Verify your runtime**
-
-   - For CLI users, make sure your Node.js version is up-to-date. The minimum required Node.js version for `rdme@9` is **v20.10.0**.
-   - The `rdme` release process is no longer publishing Docker images and the GitHub Action is now a JavaScript action. This change should not affect any GitHub Actions users.
-
-2. **Topic separator changes**
-
-   - The topic separator (i.e., what separates a command from its subcommand) has changed from a colon to a space by default. For example, `rdme openapi:validate` is now `rdme openapi validate`.
-   - The colon topic separator will continue to be supported so there is no need to change any existing commands, but all documentation and help screens will reflect the space topic separator.
-
-3. **Command replacements**
-
-   - Replace `swagger` → [`openapi`](https://github.com/readmeio/rdme/tree/v9/documentation/commands/openapi.md#rdme-openapi-spec)
-   - Replace `validate` → [`openapi validate`](https://github.com/readmeio/rdme/tree/v9/documentation/commands/openapi.md#rdme-openapi-validate-spec)
-   - Remove: `docs:edit`, `oas`
-
-4. **Version flag updates**
-
-   The CLI flags on [the `versions create` and `versions update` commands](https://github.com/readmeio/rdme/tree/v9/documentation/commands/versions.md) now maintain parity with [our API flags](https://docs.readme.com/main/reference/createversion). The `--isPublic` flag has been removed in favor of a new flag called `--hidden`, which is the inverse of `--isPublic`.
-
-   **Before**
-
-   ```bash
-   rdme versions:create 1.0.1 --isPublic true
-   ```
-
-   **After**
-
-   ```bash
-   rdme versions create 1.0.1 --hidden false
-   ```
-
-5. **Deprecated commands**
-
-   The following commands (and their subcommands) will be removed in `rdme@10`:
-
-   - `categories`
-   - `custompages`
-   - `docs` (and its `guides` alias)
-   - `versions`
-   - `open`
-
-   The `openapi` command is deprecated and will be replaced in `rdme@10` by a command with a simpler flag setup based on community feedback.
-
-6. **Verify any scripts that utilize raw CLI outputs**
-
-   - The underlying architecture for the CLI has been rewritten with [`oclif`](https://oclif.io/), so some command outputs and error messages may look different.
-   - With the exception of the `--raw` flag on `openapi`, we recommend relying on CLI exit codes in your workflows rather than raw command outputs.
-
 ## Migrating to `rdme@8`
 
 Please see [the `[email protected]` release notes](https://github.com/readmeio/rdme/releases/tag/8.0.0).
 
 ## Version Compatibility Matrix
 
-| Feature                                                                                                                                     | `v8`   | `v9`        | `v10`       |
-| ------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | ----------- |
-| Actively Maintained?                                                                                                                        | ❌     | ✅          | ✅          |
-| Support for [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored)\*                                           | ❌     | ❌          | ✅          |
-| Supports Bi-Directional Sync                                                                                                                | ❌     | ❌          | ✅          |
-| Support for Legacy Projects (i.e., not yet migrated to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored)) | ✅     | ✅          | ❌          |
-| Node.js Requirements                                                                                                                        | `>=14` | `>=20.10.0` | `>=20.10.0` |
+| Feature                                                                                                                  | `v8`   | `v9`        | `v10`       |
+| ------------------------------------------------------------------------------------------------------------------------ | ------ | ----------- | ----------- |
+| Actively Maintained?                                                                                                     | ❌     | ✅          | ✅          |
+| Support for [ReadMe Refactored](https://docs.readme.com/main/docs/migration)\*                                           | ❌     | ❌          | ✅          |
+| Supports Bi-Directional Sync                                                                                             | ❌     | ❌          | ✅          |
+| Support for Legacy Projects (i.e., not yet migrated to [ReadMe Refactored](https://docs.readme.com/main/docs/migration)) | ✅     | ✅          | ❌          |
+| Node.js Requirements                                                                                                     | `>=14` | `>=20.10.0` | `>=20.10.0` |
 
 \*If you uploaded an API definition prior to migrating your project to ReadMe Refactored, any existing workflows for syncing these files that use a legacy `rdme` version (i.e., `v9` or earlier) should continue to work, even after migrating. **For new workflows, we recommend following this migration guide and upgrading to the latest version.**
 

src/commands/categories/create.ts

@@ -19,7 +19,7 @@ export default class CategoriesCreateCommand extends BaseCommand<typeof Categori
   static state = 'deprecated';
 
   static deprecationOptions = {
-    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`,
+    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`,
   };
 
   static description = 'Create a category with the specified title and guide in your ReadMe project.';

src/commands/categories/index.ts

@@ -10,7 +10,7 @@ export default class CategoriesCommand extends BaseCommand<typeof CategoriesComm
   static state = 'deprecated';
 
   static deprecationOptions = {
-    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`,
+    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`,
   };
 
   static description = 'Get all categories in your ReadMe project.';

src/commands/custompages.ts

@@ -16,7 +16,7 @@ export default class CustomPagesCommand extends BaseCommand<typeof CustomPagesCo
   static state = 'deprecated';
 
   static deprecationOptions = {
-    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`,
+    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`,
   };
 
   static summary = 'Sync Markdown/HTML files to your ReadMe project as Custom Pages.';

src/commands/docs/index.ts

@@ -15,7 +15,7 @@ export default class DocsCommand extends BaseCommand<typeof DocsCommand> {
   static state = 'deprecated';
 
   static deprecationOptions = {
-    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`,
+    message: `\`rdme ${this.id}\` is deprecated and v10 will have a replacement command that supports ReadMe Refactored.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`,
   };
 
   static aliases = ['guides'];

src/commands/docs/prune.ts

@@ -23,7 +23,7 @@ export default class DocsPruneCommand extends BaseCommand<typeof DocsPruneComman
   static state = 'deprecated';
 
   static deprecationOptions = {
-    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`,
+    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`,
   };
 
   // this needs to be separated by a colon in order for autocomplete to work properly

src/commands/open.ts

@@ -23,7 +23,7 @@ export default class OpenCommand extends BaseCommand<typeof OpenCommand> {
   static state = 'deprecated';
 
   static deprecationOptions = {
-    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`,
+    message: `\`rdme ${this.id}\` is deprecated and will be removed in v10.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`,
   };
 
   async run() {

src/commands/openapi/index.ts

@@ -27,7 +27,7 @@ export default class OpenAPICommand extends BaseCommand<typeof OpenAPICommand> {
   static state = 'deprecated';
 
   static deprecationOptions = {
-    message: `\`rdme ${this.id}\` is deprecated and v10 will have a replacement command that supports ReadMe Refactored. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`,
+    message: `\`rdme ${this.id}\` is deprecated and v10 will have a replacement command that supports ReadMe Refactored.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`,
   };
 
   static args = {