Conversation
JLekawa
requested review from
a team
and removed request for
RomanHotsiy and
adamaltman
![redocly[bot]](https://avatars.githubusercontent.com/in/348054?s=60&v=4){kind=small}
There was a problem hiding this comment.
marketing-site AI Review: 🟢 Completed
Note
Low Risk
This PR contains documentation updates, static content changes, and redirects. The risk is minimal as it only impacts documentation navigation and backwards compatibility is handled via redirects.
Overview
Copies legacy migration guides to the docs-legacy directory and sets up redirects from their previous paths.
- Adds
migrate-from-legacy-portal.md,use-legacy-ui-components.md, andmigrate-api-reference.mdintodocs-legacy/. - Adjusts internal links inside these guides to use absolute URLs to the main Redocly documentation and strips existing frontmatter.
- Modifies
redirects.yamlto route traffic from/docs/realm/get-started/to the newdocs-legacy/paths. - Updates references in existing files (
banner-legacy-developer-portal.md,signup.md,product-timelines.md) to point to the correct locations.
Reviewer Notes
- Typo in redirect path: There is a missing leading slash in the
use-legacy-ui-componentsredirect key ('docs/realm/get-started/...') inredirects.yaml, which may cause the redirect to fail. - Redundant files: The original source files in
docs/realm/get-started/were not deleted in this PR.
| If you have your API descriptions stored in a Git repository, this repository becomes the source for your Redoc project. | ||
|
|
||
| To make your existing Git repository the source for your Redoc project: | ||
| (../../reunite/project/connect-git/connect-git-provider.md) to get the existing content connected to the new project. |
There was a problem hiding this comment.
Around line 30, the first numbered step was accidentally overwritten. Additionally, this relative path is broken as it points to a non-existent ../../reunite directory.
| @@ -0,0 +1,291 @@ | |||
| # Migrate from Workflows | |||
There was a problem hiding this comment.
There is a typo in the filename docs-legacy/workflows/migrate-api-refernce.md. It should be migrate-api-reference.md.
| to: '/docs/realm/get-started/migrate/migrate-from-legacy-portal' | ||
| '/docs/realm/get-started/migrate-api-reference': | ||
| to: '/docs/realm/get-started/migrate/migrate-api-reference' | ||
|
|
There was a problem hiding this comment.
Targets point to non-existent /docs/realm/get-started/migrate/ paths instead of docs-legacy/. The original files in docs/realm/get-started/ were not deleted, shadowing the redirects. Also, a redirect for use-legacy-ui-components.md is missing.
redirects.yaml
Outdated
| '/docs/realm/get-started/migrate-from-legacy-portal': | ||
| to: '/docs/realm/get-started/migrate/migrate-from-legacy-portal' | ||
| '/docs/realm/get-started/migrate-api-reference': | ||
| to: '/docs/realm/get-started/migrate/migrate-api-reference' |
There was a problem hiding this comment.
The newly added files in docs-legacy/ are not added to any sidebars.yaml. Meanwhile, docs/realm/sidebars.yaml still references the old un-deleted file paths. Please update the sidebars to maintain documentation structure.
| In this example, both API definitions are set up as remote content sources and the `redocly.yaml` file uses relative file paths. | ||
|
|
||
| - The art-museum uses [remote content from GitHub](../../reunite/project/remote-content/from-github.md). | ||
| - The flight-museum uses [remote content from a URL](../../reunite/project/remote-content/url.md). |
There was a problem hiding this comment.
There are broken relative links ../../reunite/project/remote-content/from-github.md and ../../reunite/project/remote-content/url.md. The reunite directory is located under docs/realm/, so these paths are incorrect.
| In this example, both API definitions are set up as remote content sources and the `redocly.yaml` file uses relative file paths. | ||
|
|
||
| - The art-museum uses [remote content from GitHub](https://www.redocly.com/docs/realm/reunite/project/remote-content/from-github.md). | ||
| - The flight-museum uses [remote content from a URL](https://www.redocly.com/docs/realm/reunite/project/remote-content/url.md). |
There was a problem hiding this comment.
Absolute URLs should not include the .md extension, as it will likely cause a 404 error on the live documentation site. Please remove the .md extension from both the GitHub and URL remote content links.
| '/docs/realm/get-started/migrate-from-legacy-portal': | ||
| to: '/docs-legacy/developer-portal/migrate-from-legacy-portal' | ||
| '/docs/realm/get-started/migrate-api-reference': | ||
| to: '/docs-legacy/workflows/migrate-api-reference' |
There was a problem hiding this comment.
The redirect target /docs-legacy/workflows/migrate-api-reference is correctly spelled, but the added file is misspelled as migrate-api-refernce.md. Please rename the file to migrate-api-reference.md to fix the typo and ensure the redirect works.
| The developer portal beta is [approaching end of life](../../pages/product-timelines/product-timelines.md). | ||
|
|
||
| Use Realm and Reunite instead. Read the [migration guide](../../docs/realm/get-started/migrate-from-legacy-portal.md). | ||
| Use Realm and Reunite instead. Read the [migration guide](../developer-portal/migrate-from-legacy-portal.md). |
There was a problem hiding this comment.
This file is used as a partial across files at different folder depths. Relative links will resolve incorrectly in deeper files. According to Redocly best practices, use absolute links inside partials (e.g., /pages/product-timelines/product-timelines.md) to ensure they resolve correctly everywhere the content is reused.
| 1. **[Sign up](https://auth.cloud.redocly.com/registration)** using the same email address you used in Workflows. This will help ensure a smooth transition. | ||
| 2. **Create your organization** - This will automatically start your free 30-day trial. | ||
| 3. **Complete the migration** - Follow our [technical migration guides](/docs/realm/get-started/migrate-api-reference) to migrate your content and configuration from Workflows to Reunite. | ||
| 3. **Complete the migration** - Follow our [technical migration guides](/docs-legacy/workflows/migrate-api-reference) to migrate your content and configuration from Workflows to Reunite. |
There was a problem hiding this comment.
The updated link points to /docs-legacy/workflows/migrate-api-reference, but the actual destination file is misspelled as migrate-api-refernce.md. This will cause a 404 error. Please rename the destination file or update the link and redirects to match.
| If you have your API descriptions stored in a Git repository, this repository becomes the source for your Redoc project. | ||
|
|
||
| To make your existing Git repository the source for your Redoc project: | ||
| (https://www.redocly.com/docs/realm/reunite/project/connect-git/connect-git-provider.md) to get the existing content connected to the new project. |
There was a problem hiding this comment.
At line 29, the markdown link is broken. The bracketed text is missing, resulting in (https://www.redocly.com/...) to get the existing content connected.... Add the missing text to fix the link, e.g., 1. [Connect your repository](...).
| @@ -0,0 +1,291 @@ | |||
| # Migrate from Workflows | |||
There was a problem hiding this comment.
The original migration files in docs/realm/get-started/ were copied here but not deleted. Because they still exist and are referenced in docs/realm/sidebars.yaml, the redirects in redirects.yaml will conflict, causing duplicate content. Delete the old files and update the sidebar.
| --- | ||
|
|
||
| - `sortTagsAlphabetically` | ||
| Try the `tags-alphabetical` decorator in the [sorting plugin](https://github.com/Redocly/redocly-cli-cookbook/tree/main/custom-plugins/sorting) from the Redocly CLI cookbook. |
There was a problem hiding this comment.
In the 'Update configuration settings' table (line 207), the entry for sortTagsAlphabetically is missing the leading dash - for the second column's replacement value. This will break the Markdoc {% table %} rendering.
|
|
||
| 1. In the project (or preview), use the dropdown to switch between versions; it retains the user's position in the API reference documentation for any entries which exist in both versions. | ||
|
|
||
| 2. (Optional) For additional control, [configure a `versions.yaml` file](https://www.redocly.com/docs/realm/content/versions.md) to specify which versions should be displayed or not, and which is the default version. |
There was a problem hiding this comment.
The list numbering around lines 86-96 and 272-282 is inconsistent (e.g., 1. 1. 1. 2. and 1. 1. 1.). Please update these lists to use sequential numbering (1. 2. 3. 4.) for better readability.
2 participants
What/Why/How?
Adds redirects to moved files
Reference
Closes https://github.com/Redocly/redocly/issues/21769
Testing
Screenshots (optional)
Check yourself
Security