Add support for theme-specific API request/response examples in Logical Theme System #4930

New Issue

OVERLORD · 2026-02-05T09:27:10+03:00

OVERLORD commented

2026-02-05 09:27:10 +03:00

Originally created by @ln-ws on GitHub (Aug 27, 2024).

Describe the feature you'd like

Implement a mechanism for BookStack to recognize and utilize API request/response examples stored within custom themes using the Logical Theme System. Currently, these examples must be manually linked to the /dev/api/requests and /dev/api/responses folders. We propose two possible solutions:

Automatically search for examples within the theme's directory structure, specifically in subfolders like /dev/api/requests and /dev/api/responses.
Allow themes to register their own examples through a defined API or configuration file.

Describe the benefits this would bring to existing BookStack users

Improved documentation: API examples would be more easily maintained and updated alongside the theme code, ensuring better synchronization between functionality and documentation.
Simplified theme management: Users would no longer need to manually create symlinks, reducing the potential for errors and streamlining the theme installation process.
Better organization: Keeping all theme-related content, including API examples, within the theme's directory structure improves code organization and makes it easier to distribute and version control themes as complete packages.
Enhanced developer experience: Theme developers would have a more intuitive and standardized way to include API examples, potentially encouraging more comprehensive documentation.
Easier theme sharing and installation: Themes could be shared as complete packages, including all necessary documentation and examples, making it simpler for users to install and use custom themes.

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

Yes, the goal can currently be achieved by manually creating symlinks from the theme's examples to the /dev/api/requests and /dev/api/responses folders.

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?

3 months to 1 year

Additional context

No response

Originally created by @ln-ws on GitHub (Aug 27, 2024). ### Describe the feature you'd like Implement a mechanism for BookStack to recognize and utilize API request/response examples stored within custom themes using the Logical Theme System. Currently, these examples must be manually linked to the /dev/api/requests and /dev/api/responses folders. We propose two possible solutions: 1. Automatically search for examples within the theme's directory structure, specifically in subfolders like /dev/api/requests and /dev/api/responses. 2. Allow themes to register their own examples through a defined API or configuration file. ### Describe the benefits this would bring to existing BookStack users 1. Improved documentation: API examples would be more easily maintained and updated alongside the theme code, ensuring better synchronization between functionality and documentation. 2. Simplified theme management: Users would no longer need to manually create symlinks, reducing the potential for errors and streamlining the theme installation process. 3. Better organization: Keeping all theme-related content, including API examples, within the theme's directory structure improves code organization and makes it easier to distribute and version control themes as complete packages. 4. Enhanced developer experience: Theme developers would have a more intuitive and standardized way to include API examples, potentially encouraging more comprehensive documentation. 5. Easier theme sharing and installation: Themes could be shared as complete packages, including all necessary documentation and examples, making it simpler for users to install and use custom themes. ### Can the goal of this request already be achieved via other means? Yes, the goal can currently be achieved by manually creating symlinks from the theme's examples to the /dev/api/requests and /dev/api/responses folders. ### 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? 3 months to 1 year ### Additional context _No response_

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

OVERLORD commented

2026-02-05 09:27:12 +03:00

@ssddanbrown commented on GitHub (Oct 14, 2024):

Thanks for the request @ln-ws, can you explain the actual real-world use-case where this is desired?

I'd just like to understand the scenario where it'd important to ensure additional added API endpoints have their own examples built in.

@ssddanbrown commented on GitHub (Oct 14, 2024): Thanks for the request @ln-ws, can you explain the actual real-world use-case where this is desired? I'd just like to understand the scenario where it'd important to ensure additional added API endpoints have their own examples built in.

OVERLORD commented

2026-02-05 09:27:15 +03:00

@zivillian commented on GitHub (Oct 14, 2024):

We wrote a logical theme which (besides other customizations) extends the api to include endpoints for token management. We are working with multiple person on extending the Logical Theme, implementing an api client and integrating the functionality in our solution. When working in a team it's great to have the api documentation in a single place.

We are versioning our theme in git. We need to install our theme in multiple bookstack instances (dev, test, prod). Our current process is to create symlinks after cloning our repository:

ln -s ../../../themes/Our.Theme/dev/api/requests/tokens-create.json dev/api/requests/.
ln -s ../../../themes/Our.Theme/dev/api/requests/tokens-update.json dev/api/requests/.

ln -s ../../../themes/Our.Theme/dev/api/responses/tokens-create.json dev/api/responses/.
ln -s ../../../themes/Our.Theme/dev/api/responses/tokens-list.json dev/api/responses/.
ln -s ../../../themes/Our.Theme/dev/api/responses/tokens-read.json dev/api/responses/.
ln -s ../../../themes/Our.Theme/dev/api/responses/tokens-update.json dev/api/responses/.

Another scenario is publishing an api extension to the BookStack Hacks Directory - it would be great if the hack also contains the documentation and examples for new API endpoints.

@zivillian commented on GitHub (Oct 14, 2024): We wrote a logical theme which (besides other customizations) extends the api to include endpoints for token management. We are working with multiple person on extending the Logical Theme, implementing an api client and integrating the functionality in our solution. When working in a team it's great to have the api documentation in a single place. We are versioning our theme in git. We need to install our theme in multiple bookstack instances (dev, test, prod). Our current process is to create symlinks after cloning our repository: ``` ln -s ../../../themes/Our.Theme/dev/api/requests/tokens-create.json dev/api/requests/. ln -s ../../../themes/Our.Theme/dev/api/requests/tokens-update.json dev/api/requests/. ln -s ../../../themes/Our.Theme/dev/api/responses/tokens-create.json dev/api/responses/. ln -s ../../../themes/Our.Theme/dev/api/responses/tokens-list.json dev/api/responses/. ln -s ../../../themes/Our.Theme/dev/api/responses/tokens-read.json dev/api/responses/. ln -s ../../../themes/Our.Theme/dev/api/responses/tokens-update.json dev/api/responses/. ``` Another scenario is publishing an api extension to the BookStack Hacks Directory - it would be great if the hack also contains the documentation and examples for new API endpoints.

OVERLORD referenced this issue

2026-02-05 10:32:03 +03:00

[PR #4930] [MERGED] JS Build: Split markdown to own file, updated packages #6431

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#4930