starred/BookStack
1
0
Fork 0
mirror of https://github.com/BookStackApp/BookStack.git synced 2026-02-05 00:29:48 +03:00
Code Issues 303 Packages Projects Releases 10 Wiki Activity

Feature Request: Include chapter name with URL path for pages #422

New Issue
Closed
opened 2026-02-04 19:47:27 +03:00 by OVERLORD · 11 comments
OVERLORD commented 2026-02-04 19:47:27 +03:00
Owner
Copy Link

Originally created by @levest28 on GitHub (Sep 6, 2017).

For Feature Requests

Desired Feature: Option to include chapter in URL

For example:

Current URL for Chapter:
https://domain.ca/books/{bookname}/chapter/{chaptername}

Current URL for Page:
https://domain.ca/books/{bookname}/page/{pagename}

Desired URL for Page:
https://domain.ca/books/{bookname}/chapter/{chaptername}/page/{pagename}

Issue:
In current setup, if I have Chapter 1 with a page "About", Chapter 2 also with "About" page is named differently.

It would be better if both chapter can refer to the page name as "About", but include the chapter name in the URL.

For documentation purpose, if we have 100+ chapters, each with an "About" page, it looks pretty messy.

Originally created by @levest28 on GitHub (Sep 6, 2017). ### For Feature Requests Desired Feature: Option to include chapter in URL For example: Current URL for Chapter: https://domain.ca/books/{bookname}/chapter/{chaptername} Current URL for Page: https://domain.ca/books/{bookname}/page/{pagename} Desired URL for Page: https://domain.ca/books/{bookname}/chapter/{chaptername}/page/{pagename} Issue: In current setup, if I have Chapter 1 with a page "About", Chapter 2 also with "About" page is named differently. It would be better if both chapter can refer to the page name as "About", but include the chapter name in the URL. For documentation purpose, if we have 100+ chapters, each with an "About" page, it looks pretty messy.
OVERLORD added the ☕ Open to discussion🔨 Feature Request labels 2026-02-04 19:47:27 +03:00
OVERLORD commented 2026-02-04 19:47:47 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Sep 6, 2017):

Hi @levest28, Thanks for opening this issue/feature request.

Reasons For

  • URL more descriptive
  • Allows a page slug to be re-used per chapter

Reasons Against

  • Will be less performant as more lookups (Or more advanced queries) to db will be needed.
  • Will complicate code further.
  • Will complicate things when coming to implement another layer of chapter.
@ssddanbrown commented on GitHub (Sep 6, 2017): Hi @levest28, Thanks for opening this issue/feature request. #### Reasons For * URL more descriptive * Allows a page slug to be re-used per chapter #### Reasons Against * Will be less performant as more lookups (Or more advanced queries) to db will be needed. * Will complicate code further. * Will complicate things when coming to implement another layer of chapter.
OVERLORD commented 2026-02-04 19:48:10 +03:00
Author
Owner
Copy Link

@nekromoff commented on GitHub (Sep 8, 2017):

Good discussion regarding URLs. From UX perspective, URLs should be as short as possible. Therefore having books/mybook/chapter/new/page/three just adds lots of clutter to URLs.

I think having URL as simple as:
mybook/new/three
makes more sense.

Anyway, this might be another config option to have URL slugs for books, chapters and pages (or not to have them defined at all).

@nekromoff commented on GitHub (Sep 8, 2017): Good discussion regarding URLs. From UX perspective, URLs should be as short as possible. Therefore having books/mybook/chapter/new/page/three just adds lots of clutter to URLs. I think having URL as simple as: mybook/new/three makes more sense. Anyway, this might be another config option to have URL slugs for books, chapters and pages (or not to have them defined at all).
OVERLORD commented 2026-02-04 19:48:28 +03:00
Author
Owner
Copy Link

@derek-shnosh commented on GitHub (Nov 15, 2018):

@ssddanbrown, I know this is a bit of an old thread, but I'd like to +1 @nekromoff's suggestion for pretty, or clean URLs.

For example;

Current URL https://docs.domain.local/books/internal-docs/page/client-pkg-virtual-machine-template
Desired URL https://docs.domain.local/internal-docs/client-pkg-virtual-machine-template

As an addition, I think user definable Slugs would be a welcome addition to page options (similar to Page Tags), and maybe even carried over to chapters and shelves, i.e.;

Example uses the same 'Current URL' from above...

Slug URL https://docs.domain.local/internal/vm-client-pkg
Book slug: internal
Page slug: vm-client-pkg

image

@derek-shnosh commented on GitHub (Nov 15, 2018): @ssddanbrown, I know this is a bit of an old thread, but I'd like to **+1** @nekromoff's suggestion for pretty, or [clean URLs](https://en.wikipedia.org/wiki/Clean_URL). For example; | Current URL | https://docs.domain.local/books/internal-docs/page/client-pkg-virtual-machine-template | | :- | :- | | Desired URL | https://docs.domain.local/internal-docs/client-pkg-virtual-machine-template | | :- | :- | As an addition, I think user definable [Slugs](https://en.wikipedia.org/wiki/Clean_URL#Slug) would be a welcome addition to page options (similar to _Page Tags_), and maybe even carried over to chapters and shelves, i.e.; _Example uses the same 'Current URL' from above..._ | Slug URL | https://docs.domain.local/internal/vm-client-pkg | | :- | :- | | | Book slug: `internal`<br>Page slug: `vm-client-pkg` | ![image](https://user-images.githubusercontent.com/21090563/48568267-db401480-e8b3-11e8-8b80-cbc1e8342adf.png)
OVERLORD commented 2026-02-04 19:48:34 +03:00
Author
Owner
Copy Link

@lieszkol commented on GitHub (Jan 6, 2020):

I'd like to add my vote to implementing slugs. It's difficult to link to pages because a page title can change at any time (thus changing the page URL), and also pages with accented characters end up with very ugly URL-s (an issue also mentioned in issue #1765 ). If one could manually set the page slug, this wouldn't be a problem.
Dan Brown I would be open to help with this if you want.

@lieszkol commented on GitHub (Jan 6, 2020): I'd like to add my vote to implementing slugs. It's difficult to link to pages because a page title can change at any time (thus changing the page URL), and also pages with accented characters end up with very ugly URL-s (an issue also mentioned in issue #1765 ). If one could manually set the page slug, this wouldn't be a problem. Dan Brown I would be open to help with this if you want.
OVERLORD commented 2026-02-04 19:48:39 +03:00
Author
Owner
Copy Link

@rclement commented on GitHub (Apr 11, 2022):

@ssddanbrown Sorry to dig up this old issue, but I have encounter a need for URLs with chapter slugs:

  • When ingesting external pages to Bookstack through the API, relative links between pages need are rewritten with deterministic URLs
  • The current /books/<book-slug>/page/<page-slug> URL form is non deterministic because of page slug de-duplication process (if 2 pages in the same book have the same slug, whatever the chapter)
  • Only the /books/<book-slug>/chapter/<chapter-slug>/page/<page-slug> URL form could provide that (given that not 2 pages in the same chapter have the same slug, but that's not Bookstack responsibility)

Would it be possible to have the best of both worlds, such as:

  • Keep the current URL form without chapters for day-to-day operations and best overall performance
  • Allow a page within a chapter to also be referenced with the chapter-based URL (without de-duplicated slugs)?
@rclement commented on GitHub (Apr 11, 2022): @ssddanbrown Sorry to dig up this old issue, but I have encounter a need for URLs with chapter slugs: - When ingesting external pages to Bookstack through the API, relative links between pages need are rewritten with deterministic URLs - The current `/books/<book-slug>/page/<page-slug>` URL form is non deterministic because of page slug de-duplication process (if 2 pages in the same book have the same slug, whatever the chapter) - Only the `/books/<book-slug>/chapter/<chapter-slug>/page/<page-slug>` URL form could provide that (given that not 2 pages in the same chapter have the same slug, but that's not Bookstack responsibility) Would it be possible to have the best of both worlds, such as: - Keep the current URL form without chapters for day-to-day operations and best overall performance - Allow a page within a chapter to also be referenced with the chapter-based URL (without de-duplicated slugs)?
OVERLORD commented 2026-02-04 19:48:44 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Apr 12, 2022):

Hi @rclement,
I understand the need here but I'm hesitant to add another URL scheme we'd need to maintain, especially since it does not directly and fully address the issue you have (Deterministic URLs), but scopes it down to a chapter level.

If you needed this ability right now you could use the below using the logical theme system (Video Guide):

<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use BookStack\Entities\Repos\ChapterRepo;
use BookStack\Exceptions\NotFoundException;
use Illuminate\Support\Facades\Route;

Theme::listen(ThemeEvents::APP_BOOT, function() {
    Route::middleware(['web', 'auth'])->group(function() {
        Route::get('/books/{bookSlug}/chapter/{chapterSlug}/page/{pageSlug}', function(ChapterRepo $chapterRepo, string $bookSlug, string $chapterSlug, string $pageSlug) {
            $chapter = $chapterRepo->getBySlug($bookSlug, $chapterSlug);
            $page = $chapter->pages()->scopes('visible')->where('slug', 'like', $pageSlug . '%')->first();
            if (!$page) {
                throw new NotFoundException(trans('errors.page_not_found'));
            }

            return redirect($page->getUrl());
        });
    });
});

This adds the desired URL endpoint for page-showing, with chapter held within, for example:

https://example.com/books/testing-book/chapter/my-chapter/page/my-page

This will then run a prefix-match using the url page slug, against the pages within that chapter, then redirect to it's standard URL if such a page is found.

Note, since this uses custom internal logic within the logical theme system much of that is technically deemed unstable/not-supported so it's advised to check such customizations upon upgrades.

@ssddanbrown commented on GitHub (Apr 12, 2022): Hi @rclement, I understand the need here but I'm hesitant to add another URL scheme we'd need to maintain, especially since it does not directly and fully address the issue you have (Deterministic URLs), but scopes it down to a chapter level. If you needed this ability right now you could use the below using the [logical theme system](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md) ([Video Guide](https://www.youtube.com/watch?v=YVbpm_35crQ)): ```php <?php use BookStack\Facades\Theme; use BookStack\Theming\ThemeEvents; use BookStack\Entities\Repos\ChapterRepo; use BookStack\Exceptions\NotFoundException; use Illuminate\Support\Facades\Route; Theme::listen(ThemeEvents::APP_BOOT, function() { Route::middleware(['web', 'auth'])->group(function() { Route::get('/books/{bookSlug}/chapter/{chapterSlug}/page/{pageSlug}', function(ChapterRepo $chapterRepo, string $bookSlug, string $chapterSlug, string $pageSlug) { $chapter = $chapterRepo->getBySlug($bookSlug, $chapterSlug); $page = $chapter->pages()->scopes('visible')->where('slug', 'like', $pageSlug . '%')->first(); if (!$page) { throw new NotFoundException(trans('errors.page_not_found')); } return redirect($page->getUrl()); }); }); }); ``` This adds the desired URL endpoint for page-showing, with chapter held within, for example: ``` https://example.com/books/testing-book/chapter/my-chapter/page/my-page ``` This will then run a prefix-match using the url page slug, against the pages within that chapter, then redirect to it's standard URL if such a page is found. Note, since this uses custom internal logic within the logical theme system much of that is technically deemed unstable/not-supported so it's advised to check such customizations upon upgrades.
OVERLORD commented 2026-02-04 19:48:55 +03:00
Author
Owner
Copy Link

@rclement commented on GitHub (Apr 12, 2022):

Thanks @ssddanbrown for your workaround!

After trying your theme customization snippet, I found an issue with the order of middleware execution:

  • Your original snippet always return a 302 redirection to /login from the browser point of view
  • It only works if web is before auth middleware
  • I am neither a Laravel nor PHP dev but I can relate to any other web framework where you need to unpack cookies/sessions before applying an auth middleware

So here is a working snippet in case anyone needs it:

<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use BookStack\Entities\Repos\ChapterRepo;
use BookStack\Exceptions\NotFoundException;
use Illuminate\Support\Facades\Route;

Theme::listen(ThemeEvents::APP_BOOT, function() {
    Route::middleware(['web', 'auth'])->group(function() {
        Route::get('/books/{bookSlug}/chapter/{chapterSlug}/page/{pageSlug}', function(ChapterRepo $chapterRepo, string $bookSlug, string $chapterSlug, string $pageSlug) {
            $chapter = $chapterRepo->getBySlug($bookSlug, $chapterSlug);
            $page = $chapter->pages()->scopes('visible')->where('slug', 'like', $pageSlug . '%')->first();
            if (!$page) {
                throw new NotFoundException(trans('errors.page_not_found'));
            }

            return redirect($page->getUrl());
        });
    });
});

@ssddanbrown Can you confirm my updated snippet?

@rclement commented on GitHub (Apr 12, 2022): Thanks @ssddanbrown for your workaround! After trying your theme customization snippet, I found an issue with the order of middleware execution: - Your original snippet always return a 302 redirection to `/login` from the browser point of view - It only works if `web` is before `auth` middleware - I am neither a Laravel nor PHP dev but I can relate to any other web framework where you need to unpack cookies/sessions before applying an auth middleware So here is a working snippet in case anyone needs it: ```php <?php use BookStack\Facades\Theme; use BookStack\Theming\ThemeEvents; use BookStack\Entities\Repos\ChapterRepo; use BookStack\Exceptions\NotFoundException; use Illuminate\Support\Facades\Route; Theme::listen(ThemeEvents::APP_BOOT, function() { Route::middleware(['web', 'auth'])->group(function() { Route::get('/books/{bookSlug}/chapter/{chapterSlug}/page/{pageSlug}', function(ChapterRepo $chapterRepo, string $bookSlug, string $chapterSlug, string $pageSlug) { $chapter = $chapterRepo->getBySlug($bookSlug, $chapterSlug); $page = $chapter->pages()->scopes('visible')->where('slug', 'like', $pageSlug . '%')->first(); if (!$page) { throw new NotFoundException(trans('errors.page_not_found')); } return redirect($page->getUrl()); }); }); }); ``` @ssddanbrown Can you confirm my updated snippet?
OVERLORD commented 2026-02-04 19:49:09 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Apr 13, 2022):

@rclement Yep! Can confirm your updated snippet. Sorry, was testing on a public dev instance when writing out my version, will update my copy to prevent copying of wrong order.

@ssddanbrown commented on GitHub (Apr 13, 2022): @rclement Yep! Can confirm your updated snippet. Sorry, was testing on a public dev instance when writing out my version, will update my copy to prevent copying of wrong order.
OVERLORD commented 2026-02-04 19:49:12 +03:00
Author
Owner
Copy Link

@martialblog commented on GitHub (Aug 25, 2023):

Any updates on this? We also have a lot of repetition in page names. I think having the option to include the chapter in the URL might be beneficial.

@martialblog commented on GitHub (Aug 25, 2023): Any updates on this? We also have a lot of repetition in page names. I think having the option to include the chapter in the URL might be beneficial.
OVERLORD commented 2026-02-04 19:49:20 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Aug 25, 2023):

@martialblog No

@ssddanbrown commented on GitHub (Aug 25, 2023): @martialblog No
OVERLORD commented 2026-02-04 19:49:24 +03:00
Author
Owner
Copy Link

@ssddanbrown commented on GitHub (Sep 7, 2025):

I'm going to go ahead and close this off as there's been little demand specifically for the format requested in the original post. I did think about revamping the URL scheme to suit a range of feedback via #3520, but ultimately I deemed changes (or complexity via variation) in this area not to realistically be worthwhile.

@ssddanbrown commented on GitHub (Sep 7, 2025): I'm going to go ahead and close this off as there's been little demand specifically for the format requested in the original post. I did think about revamping the URL scheme to suit a range of feedback via #3520, but ultimately I deemed changes (or complexity via variation) in this area not to realistically be worthwhile.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
🎨 Design
📖 Docs Update
🐛 Bug
🐛 Bug
:cat2:🐈 Possible duplicate
💿 Database
☕ Open to discussion
💻 Front-End
🐕 Support
🚪 Authentication
🌍 Translations
🔌 API Task
🏭 Back-End
⛲ Upstream
🔨 Feature Request
🛠️ Enhancement
🛠️ Enhancement
🛠️ Enhancement
❤️ Happy feedback
🔒 Security
🔍 Pending Validation
💆 UX
📝 WYSIWYG Editor
🌔 Out of scope
🔩 API Request
:octocat: Admin/Meta
🖌️ View Customization
❓ Question
🚀 Priority
🛡️ Blocked
🚚 Export System
♿ A11y
🔧 Maintenance
> Markdown Editor
No Label ☕ Open to discussion 🔨 Feature Request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
OVERLORD
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/BookStack#422
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?