diff --git a/README.md b/README.md index 0bb22fa07..a48efd8e2 100644 --- a/README.md +++ b/README.md @@ -171,6 +171,7 @@ npm run build && npm run build:docs * [`rdme autocomplete`](documentation/commands/autocomplete.md) - Display autocomplete installation instructions. * [`rdme changelogs`](documentation/commands/changelogs.md) - Upload Markdown files to your ReadMe project as Changelog posts. +* [`rdme docs`](documentation/commands/docs.md) - Upload Markdown files to the Guides section of your ReadMe project. * [`rdme help`](documentation/commands/help.md) - Display help for rdme. * [`rdme login`](documentation/commands/login.md) - Login to a ReadMe project. * [`rdme logout`](documentation/commands/logout.md) - Logs the currently authenticated user out of ReadMe. diff --git a/__tests__/commands/docs/__snapshots__/upload.test.ts.snap b/__tests__/commands/docs/__snapshots__/upload.test.ts.snap index 8a7d342c9..8fa6474d9 100644 --- a/__tests__/commands/docs/__snapshots__/upload.test.ts.snap +++ b/__tests__/commands/docs/__snapshots__/upload.test.ts.snap @@ -3,9 +3,7 @@ exports[`rdme docs upload > given that ReadMe project has bidirection sync set up > should error if validation is not skipped 1`] = ` { "error": [Error: Bi-directional syncing is enabled for this project. Uploading these docs will overwrite what's currently synced from Git. To proceed with the upload, re-run this command with the \`--skip-validation\` flag.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -", + "stderr": "", "stdout": "", } `; @@ -15,9 +13,7 @@ exports[`rdme docs upload > given that ReadMe project has bidirection sync set u "error": [APIv2Error: ReadMe API error: The API key couldn't be located. The API key you passed in (bad-api-key) doesn't match any keys we have in our system. API keys must be passed in via Bearer token. You can get your API key in Configuration > API Key, or in the docs.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -", + "stderr": "", "stdout": "", } `; @@ -37,9 +33,7 @@ exports[`rdme docs upload > given that ReadMe project has bidirection sync set u "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! - › Warning: Bi-directional syncing is enabled for this project. Uploading + "stderr": " › Warning: Bi-directional syncing is enabled for this project. Uploading › these docs will overwrite what's currently synced from Git. - 🚀 Uploading files to ReadMe... ✔ 🚀 Uploading files to ReadMe... done! @@ -83,9 +77,7 @@ exports[`rdme docs upload > given that the file path is a directory > given that "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/multiple-docs\` directory... + "stderr": "- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/multiple-docs\` directory... ✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/multiple-docs\` directory... 4 file(s) found! - 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! @@ -122,9 +114,7 @@ exports[`rdme docs upload > given that the file path is a directory > should cre "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory... + "stderr": "- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory... ✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory... 2 file(s) found! - 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! @@ -141,9 +131,7 @@ exports[`rdme docs upload > given that the file path is a directory > should cre exports[`rdme docs upload > given that the file path is a directory > should error out if the directory does not contain any Markdown files 1`] = ` { "error": [Error: The directory you provided (__tests__/__fixtures__/ref-oas) doesn't contain any of the following file extensions: .markdown, .md, .mdx.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/ref-oas\` directory... + "stderr": "- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/ref-oas\` directory... ✖ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/ref-oas\` directory... no files found. ", "stdout": "", @@ -153,9 +141,7 @@ exports[`rdme docs upload > given that the file path is a directory > should err exports[`rdme docs upload > given that the file path is a directory > should handle a mix of creates and updates and failures and skipped files (dry run) 1`] = ` { "error": [AggregateError: Multiple dry runs failed. To see more detailed errors for a page, run \`rdme docs upload \` --dry-run.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... + "stderr": "- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... ✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... 5 file(s) found! - 🔬 Validating frontmatter data... ⚠ 🔬 Validating frontmatter data... issues found in 2 file(s). @@ -181,9 +167,7 @@ exports[`rdme docs upload > given that the file path is a directory > should han exports[`rdme docs upload > given that the file path is a directory > should handle a mix of creates and updates and failures and skipped files 1`] = ` { "error": [AggregateError: Multiple page uploads failed. To see more detailed errors for a page, run \`rdme docs upload \`.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... + "stderr": "- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... ✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... 5 file(s) found! - 🔬 Validating frontmatter data... ⚠ 🔬 Validating frontmatter data... issues found in 2 file(s). @@ -247,9 +231,7 @@ exports[`rdme docs upload > given that the file path is a directory > should han }, ], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... + "stderr": "- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... ✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/mixed-docs\` directory... 5 file(s) found! - 🔬 Validating frontmatter data... ⚠ 🔬 Validating frontmatter data... issues found in 2 file(s). @@ -293,9 +275,7 @@ exports[`rdme docs upload > given that the file path is a directory > should han }, ], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/complex-frontmatter\` directory... + "stderr": "- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/complex-frontmatter\` directory... ✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/complex-frontmatter\` directory... 2 file(s) found! - 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! @@ -330,9 +310,7 @@ exports[`rdme docs upload > given that the file path is a directory > should upd }, ], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory... + "stderr": "- 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory... ✔ 🔍 Looking for Markdown files in the \`__tests__/__fixtures__/docs/existing-docs\` directory... 2 file(s) found! - 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! @@ -361,9 +339,7 @@ exports[`rdme docs upload > given that the file path is a single file > and the "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🚀 Uploading files to ReadMe... ✔ 🚀 Uploading files to ReadMe... done! @@ -377,9 +353,7 @@ exports[`rdme docs upload > given that the file path is a single file > and the exports[`rdme docs upload > given that the file path is a single file > and the command is being run in a CI environment > should error out if the file has validation errors 1`] = ` { "error": [Error: 1 file(s) have issues that should be fixed before uploading to ReadMe. Please run \`rdme docs upload __tests__/__fixtures__/docs/mixed-docs/legacy-category.md --dry-run\` in a non-CI environment to fix them.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ⚠ 🔬 Validating frontmatter data... issues found in 1 file(s). ", "stdout": "", @@ -391,9 +365,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th "error": [APIv2Error: ReadMe API error: bad request something went so so wrong], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🎭 Uploading files to ReadMe (but not really because it's a dry run)... ✖ 🎭 Uploading files to ReadMe (but not really because it's a dry run)... 1 file(s) failed. @@ -407,9 +379,7 @@ something went so so wrong], exports[`rdme docs upload > given that the file path is a single file > given that the --dry-run flag is passed > should error out if a non-404 error is returned from the GET request 1`] = ` { "error": [Error: The ReadMe API responded with an unexpected error. Please try again and if this issue persists, get in touch with us at support@readme.io.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🎭 Uploading files to ReadMe (but not really because it's a dry run)... ✖ 🎭 Uploading files to ReadMe (but not really because it's a dry run)... 1 file(s) failed. @@ -435,9 +405,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🎭 Uploading files to ReadMe (but not really because it's a dry run)... ✔ 🎭 Uploading files to ReadMe (but not really because it's a dry run)... done! @@ -463,9 +431,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th }, ], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🎭 Uploading files to ReadMe (but not really because it's a dry run)... ✔ 🎭 Uploading files to ReadMe (but not really because it's a dry run)... done! @@ -479,9 +445,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th exports[`rdme docs upload > given that the file path is a single file > given that the file has frontmatter issues > should exit if the user declines to fix the issues 1`] = ` { "error": [Error: Aborting upload due to user input.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ⚠ 🔬 Validating frontmatter data... issues found in 1 file(s). ", "stdout": "", @@ -503,9 +467,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ⚠ 🔬 Validating frontmatter data... issues found in 1 file(s). - 🚀 Uploading files to ReadMe... ✔ 🚀 Uploading files to ReadMe... done! @@ -531,9 +493,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ⚠ 🔬 Validating frontmatter data... issues found in 1 file(s). - 🚀 Uploading files to ReadMe... ✔ 🚀 Uploading files to ReadMe... done! @@ -549,9 +509,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th "error": [APIv2Error: ReadMe API error: bad request your category is whack], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! - › Warning: Skipping pre-upload validation of the Markdown file(s). This is + "stderr": " › Warning: Skipping pre-upload validation of the Markdown file(s). This is › not recommended. - 🚀 Uploading files to ReadMe... ✖ 🚀 Uploading files to ReadMe... 1 file(s) failed. @@ -577,9 +535,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ⚠ 🔬 Validating frontmatter data... issues found in 1 file(s). › Warning: 1 file(s) have issues that cannot be fixed automatically. The › upload will proceed but we recommend addressing these issues. Please get @@ -608,9 +564,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🚀 Uploading files to ReadMe... ✔ 🚀 Uploading files to ReadMe... done! @@ -636,9 +590,7 @@ exports[`rdme docs upload > given that the file path is a single file > given th }, ], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🚀 Uploading files to ReadMe... ✔ 🚀 Uploading files to ReadMe... done! @@ -664,9 +616,7 @@ exports[`rdme docs upload > given that the file path is a single file > should a "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🚀 Uploading files to ReadMe... ✔ 🚀 Uploading files to ReadMe... done! @@ -692,9 +642,7 @@ exports[`rdme docs upload > given that the file path is a single file > should c "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🚀 Uploading files to ReadMe... ✔ 🚀 Uploading files to ReadMe... done! @@ -710,9 +658,7 @@ exports[`rdme docs upload > given that the file path is a single file > should e "error": [APIv2Error: ReadMe API error: bad request something went so so wrong], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🚀 Uploading files to ReadMe... ✖ 🚀 Uploading files to ReadMe... 1 file(s) failed. @@ -726,9 +672,7 @@ something went so so wrong], exports[`rdme docs upload > given that the file path is a single file > should error out if a non-404 error is returned from the GET request 1`] = ` { "error": [Error: The ReadMe API responded with an unexpected error. Please try again and if this issue persists, get in touch with us at support@readme.io.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🚀 Uploading files to ReadMe... ✖ 🚀 Uploading files to ReadMe... 1 file(s) failed. @@ -742,9 +686,7 @@ exports[`rdme docs upload > given that the file path is a single file > should e exports[`rdme docs upload > given that the file path is a single file > should error out if the file does not exist 1`] = ` { "error": [Error: Oops! We couldn't locate a file or directory at the path you provided.], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -", + "stderr": "", "stdout": "", } `; @@ -752,39 +694,11 @@ exports[`rdme docs upload > given that the file path is a single file > should e exports[`rdme docs upload > given that the file path is a single file > should error out if the file has an invalid file extension 1`] = ` { "error": [Error: Invalid file extension (.json). Must be one of the following: .markdown, .md, .mdx], - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -", + "stderr": "", "stdout": "", } `; -exports[`rdme docs upload > given that the file path is a single file > should hide the warning if the \`--hide-experimental-warning\` flag is passed 1`] = ` -{ - "result": { - "created": [ - { - "filePath": "__tests__/__fixtures__/docs/new-docs/new-doc.md", - "response": {}, - "result": "created", - "slug": "new-doc", - }, - ], - "failed": [], - "skipped": [], - "updated": [], - }, - "stderr": "- 🔬 Validating frontmatter data... -✔ 🔬 Validating frontmatter data... no issues found! -- 🚀 Uploading files to ReadMe... -✔ 🚀 Uploading files to ReadMe... done! -", - "stdout": "🌱 Successfully created 1 page(s) in ReadMe: - - new-doc (__tests__/__fixtures__/docs/new-docs/new-doc.md) -", -} -`; - exports[`rdme docs upload > given that the file path is a single file > should not throw an error if \`max-errors\` flag is set to -1 1`] = ` { "result": { @@ -802,9 +716,7 @@ something went so so wrong], "skipped": [], "updated": [], }, - "stderr": " › Warning: This command is in an experimental alpha and is likely to change. - › Use at your own risk! -- 🔬 Validating frontmatter data... + "stderr": "- 🔬 Validating frontmatter data... ✔ 🔬 Validating frontmatter data... no issues found! - 🚀 Uploading files to ReadMe... ✖ 🚀 Uploading files to ReadMe... 1 file(s) failed. diff --git a/__tests__/commands/docs/upload.test.ts b/__tests__/commands/docs/upload.test.ts index 594d0780a..f031890f6 100644 --- a/__tests__/commands/docs/upload.test.ts +++ b/__tests__/commands/docs/upload.test.ts @@ -55,31 +55,6 @@ describe('rdme docs upload', () => { mock.done(); }); - it('should hide the warning if the `--hide-experimental-warning` flag is passed', async () => { - const mock = getAPIv2Mock({ authorization }) - .get('/versions/stable/guides/new-doc') - .reply(404) - .post('/versions/stable/guides', { - category: { uri: '/versions/stable/categories/guides/category-slug' }, - slug: 'new-doc', - title: 'This is the document title', - content: { body: '\nBody\n' }, - }) - .reply(201, {}); - - const result = await run([ - '__tests__/__fixtures__/docs/new-docs/new-doc.md', - '--key', - key, - '--hide-experimental-warning', - ]); - - expect(result).toMatchSnapshot(); - expect(fs.writeFileSync).not.toHaveBeenCalled(); - - mock.done(); - }); - it('should allow for user to specify version via --version flag', async () => { const mock = getAPIv2Mock({ authorization }) .get('/versions/1.2.3/guides/new-doc') diff --git a/documentation/commands/docs.md b/documentation/commands/docs.md index b25e05c55..2d521c940 100644 --- a/documentation/commands/docs.md +++ b/documentation/commands/docs.md @@ -7,14 +7,6 @@ Upload Markdown files to the Guides section of your ReadMe project. ## `rdme docs upload PATH` -> [!WARNING] -> This command is in an experimental alpha and is likely to change. Use at your own risk! - -
- - -I understand the risks — let's see the docs! - Upload Markdown files to the Guides section of your ReadMe project. ``` @@ -65,6 +57,3 @@ FLAG DESCRIPTIONS Defaults to `stable` (i.e., your main project version). ``` - - -
diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index acb4b381a..127754eaa 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -71,19 +71,32 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi 2. **Command Replacements** - - Replace: `openapi` → `openapi upload` (see more in step 3 below) + - Replace: `docs` (and its `guides` alias) → `docs upload` (see more in step 3 below) + - Replace: `openapi` → `openapi upload` (see more in step 4 below) - Replace: `categories` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync) - Replace: `custompages` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync) - Replace: `versions` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync) - Remove: `open` -3. **`openapi` has been replaced by `openapi upload`** +3. **`docs` has been replaced by `docs upload`** - If you previously uploaded API definitions to ReadMe via `rdme openapi`, the command is now `rdme openapi upload`. There are now two main updates: + If you previously uploaded Markdown files to your Guides section via `rdme docs`, the command is now `rdme docs upload`. The command semantics are largely the same, but with a few small changes: + + - The `--dryRun` flag has been deprecated in favor of `--dry-run`. - There is no prompt to select your ReadMe project version if you omit the `--version` flag. It now defaults to `stable` (i.e., your main ReadMe project version). - - Previously with `openapi`, the `--id` flag was an ObjectId that required an initial upload to ReadMe, which made it difficult to upsert API definitions and manage many at scale. With `openapi upload`, the `--id` flag has been renamed to `--slug` and is now optional. The slug (i.e., the unique identifier for your API definition resource in ReadMe) is inferred from the file path or URL to your API definition. + - `rdme docs upload` will now automatically validate your frontmatter and flag any issues prior to syncing. This is particularly helpful if you're coming from `rdme@9` or earlier, since the shape of certain frontmatter attributes (e.g., `category`, `parent`) have slightly changed. If you run this command in a non-CI environment, any outdated frontmatter will be detected and you'll have the ability to update it automatically. + + Read more in [the `docs upload` command docs](https://github.com/readmeio/rdme/tree/v10/documentation/commands/docs.md#rdme-docs-upload-path) and in [the ReadMe API migration guide](https://docs.readme.com/main/reference/api-migration-guide). + +4. **`openapi` has been replaced by `openapi upload`** + + If you previously uploaded API definitions to ReadMe via `rdme openapi`, the command is now `rdme openapi upload`. There are now two main updates: + + - Like `docs upload` above, there is no prompt to select your ReadMe project version if you omit the `--version` flag. It now defaults to `stable` (i.e., your main ReadMe project version). + + - The flag paradigms have been simplified based on community feedback. Previously with `openapi`, the `--id` flag was an ObjectId that required an initial upload to ReadMe, which made it difficult to upsert API definitions and manage many at scale (and workarounds were added after the fact in the form of the `--create` and `--update` flags). With `openapi upload`, the `--id` flag has been renamed to `--slug` and is now optional. The slug (i.e., the unique identifier for your API definition resource in ReadMe) is inferred from the file path or URL to your API definition. Read more in [the `openapi upload` command docs](https://github.com/readmeio/rdme/tree/v10/documentation/commands/openapi.md#rdme-openapi-upload-spec) and in [the ReadMe API migration guide](https://docs.readme.com/main/reference/api-migration-guide). @@ -169,15 +182,18 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi 5. **Deprecated commands** - The following commands (and their subcommands) will be removed in `rdme@10`: + The following commands (and their subcommands, if applicable) will be removed in `rdme@10`: - `categories` - `custompages` - - `docs` (and its `guides` alias) + - `docs:prune` (and its `guides:prune` alias) - `versions` - `open` - The `openapi` command will be replaced by `openapi upload` and will have a simpler flag setup based on community feedback. + The following commands will be replaced in `v10`. See "Command Replacements" in [the `v10` migration guide above](#migrating-to-rdme10) for more info: + + - `docs` (and its `guides` alias) → `docs upload` + - `openapi` → `openapi upload` 6. **Verify any scripts that utilize raw CLI outputs** diff --git a/src/commands/docs/upload.ts b/src/commands/docs/upload.ts index ce3d7456e..d643bebd2 100644 --- a/src/commands/docs/upload.ts +++ b/src/commands/docs/upload.ts @@ -9,16 +9,12 @@ import syncPagePath, { type UpdatePushResult, } from '../../lib/syncPagePath.js'; -const alphaNotice = 'This command is in an experimental alpha and is likely to change. Use at your own risk!'; - export default class DocsUploadCommand extends BaseCommand { id = 'docs upload' as const; route = 'guides' as const; - static hidden = true; - - static summary = `Upload Markdown files to the Guides section of your ReadMe project.\n\nNOTE: ${alphaNotice}`; + static summary = 'Upload Markdown files to the Guides section of your ReadMe project.'; static description = 'The path can either be a directory or a single Markdown file. The Markdown files will require YAML frontmatter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your frontmatter: https://docs.readme.com/main/docs/rdme#markdown-file-setup'; @@ -55,10 +51,6 @@ export default class DocsUploadCommand extends BaseCommand { - if (!this.flags['hide-experimental-warning']) { - this.warn(alphaNotice); - } return syncPagePath.call(this); } }