Bookstack: Page Transclusion

[davidPilkington]

I would find it really useful to be able to include the contents of one page on another rather than just having a link to the other page displayed.

Page A - Heading
Page A - Content
[[include Page B]]
Page A - Content
[[Include Page C]]
Page A - Content

Currently, I have links to to Page B and C but it would be great if I could have the content of that page output on Page A. This would remove the need to traverse pages to get content that needs to be displayed in multiple locations. Very helpful for pdf exports too where a link to another page is not easy to follow.

[bridgeyuwa]

Are you suggesting something similar to 'Hovercards' or popup extention in mediawiki?

[davidPilkington]

No, not really. I am suggesting adding the included page in line with the rest of the page content. More like how include or require works in php.

[LeDistordu]

+1

[kimreyio]

This is referred to normally as Transclusion. For instance, In MediaWiki, if I created a page called WebServerIP and put in 10.1.1.53 as the body text, in another document I referred to connecting to the Web Server as {{WebServerIP}}, I could also put that same type of transclusion markup in 100 other technical pages.. that way when the IP changes I don't have to go update the IP on 100 pages, just edit that one page. It's also great for leagalese and other information that changes frequently.

[Shackelford-Arden]

This would be a wonderful addition! This helps a lot with removing redundant information.

[kimreyio]

Is this at all even being considered? Or is there a donation setup for specific features? This is really the only one I'm missing.

[ssddanbrown]

Hi @kimreyio, There is no donation system currently set up. If I'm totally honest, since I did not have much of a use case for this feature myself I didn't have a lot of urgency to implement it.

I've now marked it as a feature to be in the next release.

[kimreyio]

Amazing news, Can't wait for the new release!

[ssddanbrown]

Hi all, Sorry for the delay in this. I started to tackle this feature last weekend but reading through this thread made me realise there's two slightly different, yet similar, features being asked for here:

1. (👍) A way to 'include' or 'embed' a document within another.
2. (❤️) A way to include 'snippets' of text within the content of pages.

I started work on feature 1 but then realised that by building feature 1 in a nice way (Integrated properly with the page editors) it will not cover the use case of feature 2 (Due to HTML formatting and the difference in content these two features have). Also, In regards to feature 2, I don't like the idea of people having to create whole pages only to store a simple string just to be included on other pages.

For feature 2 I propose we have a 'snippet library' which is where users can store simple strings of text within the system for the sole purpose of being included in other pages. By not trying to merge these two similar features together we can optimise their ease of use and the UI's built around them.

Since I'm a bit behind on the next release I only want to implement one of these for v0.14 then the other for the release after. Which one of these features gets added in the next release will be decided by a vote.

Using reactions on this post, react with a thumbs up (👍) for option 1 or a heart (❤️) for option 2. When I next get a chunk of time to work on a feature (Should be this weekend) I'll pick the one with the most votes.

[monitaure]

Hi there, I hesitated a lot between the options.

Option 2 is great, snippet libraries are always a good feature if you want to store data that are unrelated with the rest of the content or that can stand alone.

But if the main goal of the snippets library is to be included, option 1 can do this, even if it means to create a whole page for a simple snippet. Meanwhile, you can create a _snippets_ book that can hold these, while waiting the option 2 on the next release.

So option 1 seems better for me.

[kimreyio]

❤️ My main use case is technical, so "snippets" is an even better route for me than full page transclusion. He didn't say if you could selectively transclude parts of the page yet. Also, the html formatting features Dan brought up push me to option 2 for this release. Sounds like Option 1 might need some more work before it's full merged.

In keeping with the book spirit, having a snippets library can be good for quotes, favorite paragraph excerpts, studying purposes, and as far as technical writing goes, pulling out solutions from longer pages.

Truly amazing work thus far, Dan. I spend a majority of my day writing in BookStack and it's saved me an incredible amount of time and frustration.

[ssddanbrown]

After some thought I decided it would be best to keep things simple in BookStack and not build any major UI components around this feature but simply have it available as an option for power users.

The resultant idea is a combination of both options discussed above. Placing the syntax {{@5}} will inject the HTML from the page with and id of 5 into that location. If that page does not exist, or the user does not have permission to see it, the tag will simply be removed.

Using the syntax {{@5#bkmrk-about-my-cat}} will find content within an element with an ID of bkmrk-about-my-cat in the page with an id of 5, trim it, then inject it in (So inline text or simple inline markup can be placed). Rather than building a 'Snippet library' into BookStack that only a percentage of people may use, A user could create a 'Page of snippets' which they use as a little library instead.

I've updated the pop-up page link thingy to be able to generate the above syntax easily and there are some things to be wary of with this implementation. I'll write some friendly documentation regarding this for the next release.

I want to get the next release out tomorrow so If the above does not sound like it covers your use case please let me know ASAP.