From: Dan Brown Date: Wed, 17 Jan 2024 16:55:07 +0000 (+0000) Subject: Added docs page for attachments X-Git-Url: http://source.bookstackapp.com/website/commitdiff_plain/1115ace7c79a936fa9be0687d221c1d7724d6378 Added docs page for attachments Closes #170 --- diff --git a/content/docs/user/attachments.md b/content/docs/user/attachments.md new file mode 100644 index 0000000..96dd4ea --- /dev/null +++ b/content/docs/user/attachments.md @@ -0,0 +1,101 @@ ++++ +title = "Attachments" +date = "2024-01-17" +type = "user-doc" ++++ + +Within BookStack you can attach files & links to pages, so they can be referenced within content +and shown available for download. Access to attachments is controlled via view permissions to the +page they're uploaded to, so users can only access attachments for pages they can view in the system. + +File attachments are really just there for storage and access convenience. +BookStack does not do anything special with attachments like scan & index their contents, +since documentation content in BookStack is designed & intended to be within the text of pages. + +{{}} + +--- + +### Creating & Uploading Attachments + +Attachments can be uploaded via the sidebar when in the page editor. +The attachments section of the sidebar is represented with a paper-clip +icon and, when open, looks like this: + +![View of the BookStack page editor, with the sidebar open on an "Attachments" view, with the buttons "Upload file" and "Attach Link", along with two listed attachment boxes below labelled as a link with names "kitty-cat.jpg" and "Secret Location"](/images/docs/user/attachments-sidebar.png) + +With this open there are options to "Upload File" or "Attach Link". +You can also just drag and drop a file into that zone around the buttons to quickly +upload a file from your device. +Uploading files is the most common use-case but you can attach a link to the page +to act as a dynamic, permission-controlled, reference/URL you can use & share. + +Below the buttons is where any existing uploaded attachments can be found. +You can use the handles on the left to reorder them if needed. +There are buttons on each to delete or edit the attachment. +Via editing you can alter the attachment name in addition to the underlying file or link, while the original +attachment URL will remain the same. +There's also a button to insert the attachment into the page, as referenced in the "Using Attachments in Pages" section below. + +Keep in mind, attachments are strongly coupled to the pages they're uploaded to. +Access to an attachment is controlled via the ability to see the owning page. +If a page is deleted, the attachments uploaded to it will be deleted too! + +--- + +### Accessing Attachments + +One uploaded, attachments will show in the sidebar when viewing a page. +You can click on an attachment to open it up. +Link attachments will open in a new tab. +File attachments will download, or you can view them in a new tab +via the dropdown menu on the right of the attachment: + +![View of the sidebar when viewing a page with two attachments: a "kitty-cat.jpg" file attachment and "Secret Location" link attachment. There's also a view of the same but showing a dropdown menu on the right of the attachment, with "Download" and "Open in Tab" options](/images/docs/user/attachments-accessing.png) + +Alternatively you can hold down Ctrl (or Cmd on Mac) and then click on it directly +to open in a new tab. +Note that attachments in new tabs may still download if the file format is not deemed +safe to show via a new tab, or if that's the browser's default behaviour. + +--- + +### Using Attachments in Pages + +While attachments are listed in the sidebar when viewing a page, as shown in the section above, +you can link to attachments within the page itself which can be a common need when wanting to add context +or reference the attachment in a particular part of your documentation content. +There are a few ways to do this. + +The first method is to simply use the "link" icon button on the attachment in the sidebar. +Clicking this will insert a link into the page, at the current cursor position, with the correct +attachment URL & name. + +The second method is via drag & drop. You can drag the attachment from the sidebar using its +handle or name, and then drop it into the editor which will insert an attachment link at that location. + +![View of the page editor, with the attachments sidebar open. An attachment card named "Secret Location" is being dragged into the body of the page editor.](/images/docs/user/attachments-usage.png) + +The third is just using normal browser and editor functionality. +You can right-click and copy the URL for the attachment, then insert a link as normal into the page +using that attachment URL you just copied. + + +--- + +### Technical Details + +When you upload & download attachments, BookStack will attempt to stream files where possible so that the application +can serve large files quickly without needing to use up system memory or increase the PHP memory limit. +If your instance is using S3-based storage, then attachments are streamed from BookStack to server +but not from S3 (or similar) to BookStack at this time, so it may be better to store and serve attachments +direct from storage if possible in those large-file circumstances. + +Even with streaming, you can often run into server-side (and proxy) upload/download/timeout limits. +Our [admin documentation on file uploads](/docs/admin/upload-config/#changing-upload-limits) may help if you run into these. + +When attachments are served inline (opened in new tab or with an `open=true` query parameter) +BookStack will attempt to sniff the mime-type of the attachment content, then serve the file +with that mime-type to allow in-browser viewing if supported, and if the detected mime-type +is deemed safe (For example, HTML won't be served inline). +This is done via an internal allow-list of mime-type values. \ No newline at end of file diff --git a/content/docs/user/searching.md b/content/docs/user/searching.md index 79a2915..cc8ab30 100644 --- a/content/docs/user/searching.md +++ b/content/docs/user/searching.md @@ -13,9 +13,11 @@ Below is a list of search functions within BookStack: * **Book/Chapter Search Bar** - When viewing a book or chapter a search bar can be found in the top of the left sidebar. These searches will look across all child items. * **Move & Link Selection** - When choosing to move a page/chapter or when selecting a page/chapter/book to link to within the editor the most popular items are shown but you also have the ability to search. +{{}} + --- -## Advanced Search Syntax +### Advanced Search Syntax All of the above search locations within BookStack share the ability to use advanced search syntax. An easy way to see this syntax in action is to use the global search in BookStack then play with the search filters which will update the search term with the below syntax. Below are details of the different types of syntax that can be used: @@ -66,7 +68,7 @@ All of the above search locations within BookStack share the ability to use adva --- -## Available Filters +### Available Filters Filters are set advanced search features that can be used in your search term. The below table shows all the filters available in BookStack and how they can be used. @@ -182,7 +184,7 @@ Filters are set advanced search features that can be used in your search term. T --- -## Search Examples +### Search Examples Below are some examples of using the above syntax and filters with descriptions: diff --git a/static/images/docs/user/attachments-accessing.png b/static/images/docs/user/attachments-accessing.png new file mode 100644 index 0000000..1e17908 --- /dev/null +++ b/static/images/docs/user/attachments-accessing.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b5a68869661ecc79c60c22310f23d42e5a8f7b70b424f127f0b9699a48001615 +size 34301 diff --git a/static/images/docs/user/attachments-sidebar.png b/static/images/docs/user/attachments-sidebar.png new file mode 100644 index 0000000..39d9eec --- /dev/null +++ b/static/images/docs/user/attachments-sidebar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:38936cb8acc1816f68db18db4bb824ccef255a855efce73c29d82cd8f005f2df +size 101703 diff --git a/static/images/docs/user/attachments-usage.png b/static/images/docs/user/attachments-usage.png new file mode 100644 index 0000000..533a499 --- /dev/null +++ b/static/images/docs/user/attachments-usage.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:77cece621560bcdefa4a714f06966c19e8480938dbe7390e6493d44761d64bc0 +size 78043 diff --git a/themes/bookstack/layouts/partials/menu_user_docs.html b/themes/bookstack/layouts/partials/menu_user_docs.html index fc7826f..4cbda2c 100644 --- a/themes/bookstack/layouts/partials/menu_user_docs.html +++ b/themes/bookstack/layouts/partials/menu_user_docs.html @@ -13,6 +13,7 @@
  • Searching Content
  • Default (WYSIWYG) Editor
  • Markdown Editor
  • +
  • Attachments
  • Drawings & Diagrams