Merge branch 'patch-1'

[website] / content / docs / user / reusing-content.md

diff --git a/content/docs/user/reusing-content.md b/content/docs/user/reusing-content.md
index 2d7240d51918d2a926980cd12e36c0a774d18be0..ca688237905d3ed50b9eaba9455f1f88bf38fa0f 100644 (file)
--- a/content/docs/user/reusing-content.md
+++ b/content/docs/user/reusing-content.md
@@ -8,9 +8,19 @@ slug = "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. By using include tags you can include entire other pages and 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.
+{{<toc>}}
 
-## Include Tags
+
+### Considerations
+
+Here are some things to consider when reusing page content via include tags:
+
+- Permissions are enforced upon includes, so content will only be included from pages that the current user has permission to view. Includes are not obvious nor transparent when viewing a page so it could be easy for a user to externally share content, containing permission-controlled included content, with a non-privileged user without thinking about what permission controls may be in use.
+- Includes work with up to three levels of nesting, limited to ensure system performance and to prevent recursion issues.
+- Included content won't be indexed as searchable content for pages they're included into.
+- Included content won't be shown within content preview text or snippets.
+
+### Include Tags
 
 To include the content of a page within another you can use the following syntax:
 
@@ -23,7 +33,7 @@ Here are some examples of this in use:
 
 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
+### 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.
@@ -34,7 +44,7 @@ By default this contains a direct link to that content. If you click the link ic
     <source src="/images/2017/01/bookstack-includes-popover.mp4" type="video/mp4">
 </video>
 
-## Forcing Content IDs
+### Forcing Content IDs
 
 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 with every save based on the content so while it may remain the same there's a good chance an ID can change therefore it's recommended to force an ID if you're using the content for includes.
 
@@ -59,4 +69,4 @@ Copyright BookStack Enterprises 2020
 
 # Revised with ID
 <p id="bkmrk-include-copyright-text">Copyright BookStack Enterprises 2020</p>
-```
+```
\ No newline at end of file