Summary
Apollo needs a compatibility layer for existing Docsify-era URLs when migrating to Clarify.
Problem
Apollo has accumulated many existing links and bookmarks that use Docsify-style routing and anchors, including:
/#/... routes?id= heading anchors- direct
.md links
- links embedded in docs content, portal pages, templates, and external references
Clarify uses clean paths and standard hash anchors, so old URLs will not automatically resolve to the new structure.
Why this matters
Without a compatibility strategy, the migration will break:
- user bookmarks
- search engine results
- external links from blog posts, issues, and discussions
- internal links embedded across Apollo docs and UI surfaces
Scope
We should provide a migration path that maps old Docsify URLs to Clarify URLs, ideally with a client-side redirect or equivalent mechanism.
Examples:
https://www.apolloconfig.com/#/zh/portal/apollo-user-guide -> /zh/portal/apollo-user-guide/#/zh/portal/apollo-user-guide?id=_71-安全相关 -> /zh/portal/apollo-user-guide#71-安全相关zh/design/apollo-design.md?id=... -> corresponding clean path + standard anchor
Possible implementation directions
- Add a lightweight client-side compatibility handler on the root page.
- Parse legacy
/#/... and ?id= URLs and rewrite them to Clarify paths.
- Keep the solution isolated so it does not interfere with normal Clarify routing.
- Add automated checks for page paths, anchors, and static assets during migration.
Acceptance criteria
- Legacy Docsify-style URLs resolve to the equivalent Clarify pages.
- Existing bookmarks and external links continue to work after the migration.
- The compatibility logic does not break normal Clarify clean-path navigation.
Notes
This issue is specifically about Clarify-side support for migration compatibility, not about Apollo deployment choice or content cleanup.
Summary
Apollo needs a compatibility layer for existing Docsify-era URLs when migrating to Clarify.
Problem
Apollo has accumulated many existing links and bookmarks that use Docsify-style routing and anchors, including:
/#/...routes?id=heading anchors.mdlinksClarify uses clean paths and standard hash anchors, so old URLs will not automatically resolve to the new structure.
Why this matters
Without a compatibility strategy, the migration will break:
Scope
We should provide a migration path that maps old Docsify URLs to Clarify URLs, ideally with a client-side redirect or equivalent mechanism.
Examples:
https://www.apolloconfig.com/#/zh/portal/apollo-user-guide->/zh/portal/apollo-user-guide/#/zh/portal/apollo-user-guide?id=_71-安全相关->/zh/portal/apollo-user-guide#71-安全相关zh/design/apollo-design.md?id=...-> corresponding clean path + standard anchorPossible implementation directions
/#/...and?id=URLs and rewrite them to Clarify paths.Acceptance criteria
Notes
This issue is specifically about Clarify-side support for migration compatibility, not about Apollo deployment choice or content cleanup.