Feature Request: Extend Historical Slug Tracking to Books and Chapters for Complete URL Stability #5448

New Issue

OVERLORD · 2026-02-05T10:04:34+03:00

OVERLORD commented

2026-02-05 10:04:34 +03:00

Originally created by @oopen on GitHub (Oct 8, 2025).

Describe the feature you'd like

Redirect from 404 to 301, a page when the book/chapter title change

Describe the benefits this would bring to existing BookStack users

No more 404 ! When page/chapter/book titles change.

Can the goal of this request already be achieved via other means?

Do NOT USE {SLUG} routing, USE permalink /link/{ID}
But the actual chapter/book slug history is lost !

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundamental request

How long have you been using BookStack?

1 to 5 years

Additional context

BookStack currently no support for recovering from slug changes. Thanks to PR #5826, which introduced a middleware that redirects requests containing old page slugs to the stable permalink (/link/{id}) by leveraging the page_revisions table. This is a valuable improvement that handles cases where only the page slug has changed.

However, this solution is incomplete because it does not address slug changes at the book or chapter level—a common and equally disruptive scenario.

🧩 The Core Problem

In BookStack, a page’s public URL is structured as:

/book-slug/page-slug (if not in a chapter), or
/book-slug/chapter-slug/page-slug (if in a chapter).

If either the book or chapter slug is modified, all existing URLs to pages within that book or chapter break permanently, even if the page slug itself remains unchanged. For example:

Original URL: /project-docs/api-guide/getting-started
After renaming the book “Project Docs” → “Product Docs”:
/project-docs/... returns a 404, despite the page still existing at /product-docs/api-guide/getting-started.

This happens because:

BookStack does not store historical slugs for books or chapters (no book_revisions or chapter_revisions tables exist).
The page_revisions table includes book_slug (as it was at revision time) but not chapter_slug.
Therefore, it is impossible to reconstruct the full historical URL when a book or chapter has been renamed.

As a result, PR #5826 cannot redirect these broken URLs, because the middleware only matches the page slug and assumes the current book/chapter path is valid—which it is not if those containers were renamed.

🎯 Proposed Solution

To enable complete and reliable redirection of all historical URLs, we propose adding revision tracking for books and chapters by introducing:

A book_revisions table (columns: book_id, slug, name, created_at)
A chapter_revisions table (columns: chapter_id, slug, name, created_at)

This would allow:

Accurate reconstruction of any past URL (e.g., /old-book/old-chapter/old-page).
A 404 handler or enhanced middleware to issue 301 redirects from any historical path to the current canonical URL.
Full alignment with BookStack’s existing page revision model, ensuring consistency across all entity types.

🔍 Why This Matters

SEO: Prevents loss of search engine ranking due to 404s.
User Trust: Shared or bookmarked links remain functional.
Enterprise Reliability: External systems (CI/CD, monitoring, integrations) can safely link to BookStack content.
Long-Term Viability: BookStack is often used as a permanent knowledge base—its URLs should be equally permanent or recoverable.

✅ Backward Compatibility & Implementation

This change would be fully backward-compatible:

New tables are optional for redirection logic; existing installs remain unaffected.
The feature would only activate when historical slugs are needed (e.g., on 404).
It follows the same pattern already established by page_revisions.

🙏 Conclusion

While PR #5826 was a great first step, true URL stability requires preserving slug history for all path components—not just pages. Adding revision tables for books and chapters would close this gap and make BookStack significantly more robust as a documentation platform.

Thank you for considering this enhancement!

Originally created by @oopen on GitHub (Oct 8, 2025). ### Describe the feature you'd like Redirect from 404 to 301, a page when the book/chapter title change ### Describe the benefits this would bring to existing BookStack users No more 404 ! When page/chapter/book titles change. ### Can the goal of this request already be achieved via other means? Do NOT USE {SLUG} routing, USE permalink /link/{ID} But the actual chapter/book slug history is lost ! ### Have you searched for an existing open/closed issue? - [x] I have searched for existing issues and none cover my fundamental request ### How long have you been using BookStack? 1 to 5 years ### Additional context BookStack currently no support for recovering from slug changes. Thanks to **[PR #5826](https://github.com/BookStackApp/BookStack/pull/5826)**, which introduced a middleware that redirects requests containing **old page slugs** to the stable permalink (`/link/{id}`) by leveraging the `page_revisions` table. This is a valuable improvement that handles cases where only the **page slug** has changed. However, this solution is **incomplete** because it does **not address slug changes at the book or chapter level**—a common and equally disruptive scenario. ### 🧩 The Core Problem In BookStack, a page’s public URL is structured as: - `/book-slug/page-slug` (if not in a chapter), or - `/book-slug/chapter-slug/page-slug` (if in a chapter). If **either the book or chapter slug is modified**, **all existing URLs to pages within that book or chapter break permanently**, even if the page slug itself remains unchanged. For example: - Original URL: `/project-docs/api-guide/getting-started` - After renaming the book “Project Docs” → “Product Docs”: `/project-docs/...` returns a 404, despite the page still existing at `/product-docs/api-guide/getting-started`. This happens because: - BookStack **does not store historical slugs** for books or chapters (no `book_revisions` or `chapter_revisions` tables exist). - The `page_revisions` table includes `book_slug` (as it was at revision time) but **not `chapter_slug`**. - Therefore, it is **impossible to reconstruct the full historical URL** when a book or chapter has been renamed. As a result, **PR #5826 cannot redirect these broken URLs**, because the middleware only matches the page slug and assumes the current book/chapter path is valid—which it is not if those containers were renamed. ### 🎯 Proposed Solution To enable **complete and reliable redirection of all historical URLs**, we propose adding revision tracking for books and chapters by introducing: - A `book_revisions` table (columns: `book_id`, `slug`, `name`, `created_at`) - A `chapter_revisions` table (columns: `chapter_id`, `slug`, `name`, `created_at`) This would allow: 1. Accurate reconstruction of any past URL (e.g., `/old-book/old-chapter/old-page`). 2. A 404 handler or enhanced middleware to issue **301 redirects** from any historical path to the current canonical URL. 3. Full alignment with BookStack’s existing page revision model, ensuring consistency across all entity types. ### 🔍 Why This Matters - **SEO**: Prevents loss of search engine ranking due to 404s. - **User Trust**: Shared or bookmarked links remain functional. - **Enterprise Reliability**: External systems (CI/CD, monitoring, integrations) can safely link to BookStack content. - **Long-Term Viability**: BookStack is often used as a permanent knowledge base—its URLs should be equally permanent or recoverable. ### ✅ Backward Compatibility & Implementation This change would be **fully backward-compatible**: - New tables are optional for redirection logic; existing installs remain unaffected. - The feature would only activate when historical slugs are needed (e.g., on 404). - It follows the same pattern already established by `page_revisions`. ### 🙏 Conclusion While **PR #5826 was a great first step**, true URL stability requires preserving slug history for **all path components**—not just pages. Adding revision tables for books and chapters would close this gap and make BookStack significantly more robust as a documentation platform. Thank you for considering this enhancement!

OVERLORD added the 🔨 Feature Request label 2026-02-05 10:04:34 +03:00

OVERLORD closed this issue

2026-02-05 10:04:36 +03:00

OVERLORD commented

2026-02-05 10:04:38 +03:00

@oopen commented on GitHub (Oct 8, 2025):

In addition, the best and most professional solution is : Implement a Permalink System with Automatic Redirects.

It is the only option that completely solves the problem for all users—past, present, and future—without any negative side effects like broken links or poor SEO. While it is the most complex to build, it is the "correct" way to handle this in a content management system and would be a massive quality-of-life improvement for all BookStack users.

Propositions to archive this : disabling the variable {SLUG} routing and using the actual {ID} or generating a {UUID} will be better

@oopen commented on GitHub (Oct 8, 2025): In addition, the best and most professional solution is : **Implement a Permalink System with Automatic Redirects**. It is **the only option** that completely solves the problem for all users—past, present, and future—without any negative side effects like broken links or poor SEO. While it is the most complex to build, it is the "correct" way to handle this in a content management system and would be a massive quality-of-life improvement for all BookStack users. Propositions to archive this : disabling the variable {SLUG} routing and using the actual {ID} or generating a {UUID} will be better

OVERLORD commented

2026-02-05 10:04:38 +03:00

@oopen commented on GitHub (Oct 8, 2025):

This is a mitigation hack c7b909aecb

@oopen commented on GitHub (Oct 8, 2025): This is a mitigation hack https://codeberg.org/bookstack/hacks/pulls/11/commits/c7b909aecbbe238b7ee5cea1a2cfd7a63eca3c15

OVERLORD commented

2026-02-05 10:04:40 +03:00

@bridgeyuwa commented on GitHub (Oct 10, 2025):

I strongly support this proposal.

Extending historical slug tracking and automatic 301 redirects to books, chapters, pages, and shelves would make BookStack’s URL system truly robust and future-proof. It directly solves the long-standing issue where renaming or reorganizing any of these items can break external links or harm SEO.

The current design idea feels solid, it maintains backward compatibility, enhances SEO, and builds user trust in shared links.

Suggested Improvements

Include shelves in the redirect logic since they often act as key navigation hubs or entry points.
Add an optional admin setting like Enable Historical Redirects so self-hosted instances can toggle the behavior.
Provide redirect logging or metrics in the admin panel to monitor usage of legacy links.
Consider caching old → new slug mappings (Redis or existing cache layer) for performance efficiency on large instances.

This feature would bring BookStack’s link stability closer to what’s expected from full-featured CMS platforms, while keeping its clean, readable URLs intact.

@bridgeyuwa commented on GitHub (Oct 10, 2025): I strongly support this proposal. Extending historical slug tracking and automatic **301 redirects** to **books, chapters, pages, and shelves** would make BookStack’s URL system truly robust and future-proof. It directly solves the long-standing issue where renaming or reorganizing any of these items can break external links or harm SEO. The current design idea feels solid, it maintains backward compatibility, enhances SEO, and builds user trust in shared links. ## Suggested Improvements - **Include shelves** in the redirect logic since they often act as key navigation hubs or entry points. - Add an **optional admin setting** like `Enable Historical Redirects` so self-hosted instances can toggle the behavior. - Provide **redirect logging or metrics** in the admin panel to monitor usage of legacy links. - Consider **caching old → new slug mappings** (Redis or existing cache layer) for performance efficiency on large instances. This feature would bring BookStack’s link stability closer to what’s expected from full-featured CMS platforms, while keeping its clean, readable URLs intact.

OVERLORD commented

2026-02-05 10:04:40 +03:00

@ssddanbrown commented on GitHub (Oct 11, 2025):

Thanks for the request @oopen and the input @bridgeyuwa, but I'm going to close this off as a duplicate of existing issue #5411.

This is something I'm wanting to implement soon, but I'm awaiting some significant database changes to be made first (ongoing in #5800) before moving onto this.

@ssddanbrown commented on GitHub (Oct 11, 2025): Thanks for the request @oopen and the input @bridgeyuwa, but I'm going to close this off as a duplicate of existing issue #5411. This is something I'm wanting to implement soon, but I'm awaiting some significant database changes to be made first (ongoing in #5800) before moving onto this.

OVERLORD commented

2026-02-05 10:04:42 +03:00

@ssddanbrown commented on GitHub (Oct 11, 2025):

Also, please avoid using AI to fill/write issues & comments within this project, it adds a lot of extra noise and I'd rather that time is focused on reading human thought/content.

@ssddanbrown commented on GitHub (Oct 11, 2025): Also, please avoid using AI to fill/write issues & comments within this project, it adds a lot of extra noise and I'd rather that time is focused on reading human thought/content.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#5448