User Documentation

Reusing Page Content

Within BookStack you may find that you want to include the same block of content in multiple places. You could copy and paste that content into multiple pages but then, if that content needs to be changed, you’d have to update it multiple times across different pages. Introduced in BookStack v0.14 is the ability to include other pages and to also include single blocks of content from other pages.

Note that the include behaviour is non-recursive so including will only work to a single level. This ensures performance and prevents users from breaking pages by creating include loops.

Include Tags

To include the content of a page within another you can used the following syntax:

{{@page_id}} or @{{page_id#content_id}}

Here are some examples of this in use:

  • {{@5}} - Include all content from the page with an id of ‘5’.
  • {{@10#bkmrk-copyright-year}} - Include the content within the element of id bkmrk-copyright-year in the page with an id of ‘10’.

You simply enter that in the page editor and then, When the page is viewed, the content will be dynamically be fetched. This means you can update the referenced content and it will show the same changes on any page the content is included within.

Easily Grabbing the Syntax

Finding the id of a page can be difficult so a quick and easy way to find include tags is built into BookStack. View a page with some content you want to re-use. Use your mouse to select some content and you will see a popup appear. By default this contains a direct link to that content. If you click the link icon on the left it will switch to show you the include tag for that content. Simply copy that and place it in another page. Remove the # and content id to include the whole content of the page instead of just a single block.

Forcing Content ID’s

When including a specific block of content the id of the block is used (part after the hash). By default these are generated by BookStack when you save a page. If you are using the WYSIWYG editor the id will stay the same unless the block is removed or re-formatted. In the markdown editor it changes every save and references the content so while it may remain the same there’s a good chance an ID can change.

Due to the fact ID’s can change it’s recommended to force ID’s on you content:

WYSIWYG Editor

In the WYSIWYG editor you can force an ID by going into the source code view and adding it manually:

Forcing WYSIWYG Ids

Markdown Editor

In the markdown editor you can simply insert HTML with an ID to ensure it does not change:

# Old Content
Copyright BookStack Enterprises 2017

# Revised with ID
<p id="include-copyright-text">Copyright BookStack Enterprises 2017</p>