Automatic Redirect Feature for Documentation Changes

[Benjamin-SCAYLE]

Background

We maintain a large and complex documentation system that spans multiple spaces and includes auto-rendered API specifications. Recently, we have been reorganizing content, renaming chapters, and moving sections, which has resulted in broken links. Customers frequently report that their saved bookmarks no longer work, leading to dissatisfaction and frustration.

Current Issue

• Manual re-linking of moved or renamed content is a time-consuming process, which involves manually setting redirects in Gitbook or other platforms.
• Given the frequent changes in content organization, this manual process increases the likelihood of missing critical redirects, leading to broken links for users.
• User experience is negatively impacted, resulting in more support tickets related to broken or missing content.

Proposed Solution

An Automatic Redirect Feature that tracks content changes and ensures a seamless user experience by redirecting users from old URLs to new ones when content is renamed or moved.

Benefits

• Reduced customer complaints about broken bookmarks and missing content.
• Streamlined content management with automatic redirects, reducing manual effort.
• Improved SEO with better link handling and URL persistence.
• Enhanced user experience as customers are seamlessly redirected to relevant content without encountering broken links.

Potential Risks

• Incorrect mapping of URLs could lead to redirects to unintended content.
• There may be a performance overhead if changes are tracked inefficiently.

[SamyPesse]

Hi @Benjamin-SCAYLE, We should already automatically set up redirects when pages are moved/renamed.

Are you using the GitHub application to edit the content or pushing commits on GitHub/GitLab?
If your content is public, feel free to share here some cases and we'll investigate. If the content is not public, can you reach out to support with some details (urls) so that we can investigate what is happening?

[Benjamin-SCAYLE]

Hey @SamyPesse,

Thanks for your quick reply. We're editing the content using Gitbook's UI, syncing it to GitLab, and have our own custom frontend solution. That's why I wasn't aware of this feature. As far as I know, redirects are managed internally within Gitbook and aren’t included in the GitLab/GitHub sync, correct?

[SamyPesse]

Yes, these redirects are managed directly within GitBook. The redirects that are in the .gitbook.yaml are manual redirects (created by users and imported in GitBook).

If you are using our frontend, you can use our API to resolve redirects. This is what our own frontend is doing:

1. Try to resolve the path in the entire local revision
2. If not found, fallback to an API call to get a page by its path (our API will take care of looking up for internal redirects)

The API being used is api.gitbook.com/v1/spaces/{spaceId}/content/path/{pagePath}. The pagePath needs to be URL encoded.

See our frontend code at https://github.com/GitbookIO/gitbook/blob/main/packages/gitbook/src/app/(space)/fetch.ts#L162-L176

[Benjamin-SCAYLE]

Good Point. This will solve our problem. thx