Improved guidance around sorting permissions

diff --git a/content/docs/user/organising-content.md b/content/docs/user/organising-content.md
index 90c80920fb7203435fdb90856200dd2a3b636513..72ae5699b33cf02ed3e4c08fd45d852ded105b97 100644 (file)
--- a/content/docs/user/organising-content.md
+++ b/content/docs/user/organising-content.md
@@ -7,7 +7,7 @@ type = "user-doc"
 
 Once your BookStack instance starts to grow you will find that you may want to re-organise your content. Within BookStack there are two options for moving content around; Either you can move pages and chapters individually or you can sort entire books.
 
-Note that to move content you will need to have 'edit' permission for both the content being moved and the parent it's being moved into.
+{{<toc>}}
 
 ### Moving Single Pages & Chapters
 
@@ -17,6 +17,8 @@ Pages and chapters can be moved directly to a new chapter or book. To move a cha
 
 Clicking the 'Move' action will take you to a screen where you can select a new location for your chapter or page. Here you can search for a particular book or chapter using the search bar at the top of the selection screen. Once you select a new parent for your chapter or page press 'Move Page' or 'Move Chapter' and your chapter or page will be moved to the new chapter or book. If you move a chapter all child pages will remain in that chapter and any related activity will now show up under the new parent book.
 
+To understand the permissions required for moving content, see the ["Permissions Required for Sorting" section](#permissions-required-for-sorting) below.
+
 ### Sorting Books
 
 The 'Book Sort' interface allows you to move multiple pages and chapters with ease in a simple drag and drop interface. To sort the content of a Book content, open the Book and find the "Sort" option within the actions list.
@@ -25,6 +27,25 @@ The 'Book Sort' interface allows you to move multiple pages and chapters with ea
 
 Initially, just the book you came from will show on the left. You can add extra books into the sort interface by selecting them on the right. Here you can simply drag and drop chapters and pages around and also between different books. Once you have organised your content press 'Save' and all included books will be re-organised.
 
+#### Permissions Required for Sorting
+
+Since content during a sort can be moved to new locations, the results of sorting can alter the applied visibility & permissions of your content.
+Due to this, moving an item requires quite a few permissions. 
+For sorting changes to apply, the following permissions are needed (considered per sorted item):
+
+- **Edit** permission on item being moved.
+- **Edit** permission on the original pre-sort parent.
+- If item is moving to a new parent book/chapter:
+    - **Edit** permission on new parent.
+    - **Create** permission for content type within new parent.
+    - **Delete** permission for content type within pre-sort parent.
+
+For example, if I wanted to move page `Page A` from `Book A` to `Book B`, I'd need:
+
+- Edit permissions for: `Page A`, `Book A` and `Book B`
+- Create permissions for pages in `Book B`
+- Delete permissions for pages in `Book A`
+
 ### Books & Shelves
 
 A bookshelf can contain multiple books and a book can be on multiple shelves. To add an existing book to a shelf start by opening the shelf you wish to move the book to and then press "Edit". Under the "Add books to this shelf" section find & select the book that you wish to move into the shelf you are currently editing and then choose "Save Shelf". Within that same interface you can alternatively drag books between the two lists, and you can drag books around in the left-hand list to dictate the default ordering of books within that shelf.