Вложения [Attachments]

В BookStack вы можете прикреплять файлы и ссылки к страницам, чтобы они могли быть использованы в содержании и предложены для скачивания. Доступ к вложениям контролируется через разрешения просмотра страницы, куда они загружены, поэтому пользователи могут получить доступ только к тем вложениям, которые связаны с видимыми для них страницами.

Основные цели вложений — это хранение файлов и удобство доступа к ним. BookStack не делает ничего особенного с вложениями, например, сканирует и индексирует их содержимое, так как документация в BookStack предназначена для размещения непосредственно в тексте страниц.

Создание и загрузка вложений

Вложения можно загружать через боковую панель, находясь в редакторе страницы. Раздел вложений обозначен иконкой скрепки, и когда он открыт, выглядит так:

Здесь доступны варианты «Загрузить файл» или «Прикрепить ссылку». Вы также можете просто перетащить файл в зону вокруг кнопок, чтобы быстро загрузить файл с устройства. Загрузка файлов — самый распространенный случай, но вы также можете прикрепить ссылку к странице, чтобы использовать её как динамичную, контролируемую ссылку/URL, которую можно использовать и делиться ею.

Под кнопками размещаются существующие вложения. Вы можете использовать ручки слева, чтобы изменять их порядок, если это необходимо. Есть кнопки для удаления или редактирования каждого вложения. Через редактирование можно изменить имя вложения, а также сам файл или ссылку, сохранив оригинальный URL вложения. Также имеется кнопка для вставки вложения в саму страницу, как описано в следующем разделе.

Обратите внимание, что вложения тесно связаны с теми страницами, к которым они были загружены. Доступ к вложению определяется возможностью видеть основную страницу. Если страница удаляется, то вместе с ней удаляются и все прикрепленные к ней вложения!

Доступ к вложениям

После загрузки вложения будут отображаться в боковой панели при просмотре страницы. Вы можете щелкнуть на вложение, чтобы открыть его. Вложение-ссылка откроет новую вкладку браузера. Файловые вложения будут загружены или открыты в новой вкладке через выпадающее меню справа от вложения:

Альтернативно, вы можете удерживать Ctrl (Cmd на Mac) и щелкнуть на вложении, чтобы оно открылось в новой вкладке. Обратите внимание, что вложения в новых вкладках могут все равно загрузиться, если формат файла считается небезопасным для отображения в новой вкладке или если это поведение браузера по умолчанию.

Использование вложений в страницах

Хотя вложения отображаются в боковой панели при просмотре страницы, вы также можете ссылаться на них непосредственно в самой странице, что часто бывает полезно, когда хочется добавить контекст или сослаться на вложение в определенной части документа. Есть несколько способов сделать это.

Первый способ — просто использовать кнопку «ссылка» на вложении в боковой панели. Щелчок на неё вставит ссылку на вложение в текущее положение курсора в редакторе с правильным URL и именем вложения.

Второй способ — это перетаскивание. Вы можете перетащить вложение из боковой панели, удерживая его ручку или имя, и затем отпустить его в редакторе, что вставит ссылку на вложение в нужное место.

Третий способ — обычное использование функционала браузера и редактора. Вы можете скопировать URL вложения, щелкнув правой кнопкой мыши, и затем вставить ссылку обычным способом в страницу, используя скопированный URL вложения.

Технические детали

При загрузке и скачивании вложений BookStack пытается передавать файлы потоковым методом, чтобы приложение могло обслуживать большие файлы быстро, не расходуя память системы или увеличивая лимит памяти PHP. Если ваш экземпляр использует хранилище на основе S3, то вложения передаются потоково с BookStack на сервер, но пока еще не передаются с S3 (или аналогичного сервиса) на BookStack, поэтому может быть предпочтительнее хранить и обслуживать вложения напрямую из хранилища в случаях больших файлов.

Даже с потоковой передачей, вы можете столкнуться с ограничениями сервера (и прокси) на загрузку, скачивание и таймауты. Наша административная документация по загрузке файлов может помочь, если вы столкнетесь с такими проблемами.

Когда вложения открываются встроенно (в новой вкладке или с параметром open=true), BookStack попытается распознать MIME-тип вложения и передать файл с этим типом, чтобы обеспечить просмотр в браузере, если это поддерживается, и если обнаруженный MIME-тип считается безопасным (например, HTML не будет передан встроенно). Это делается с помощью внутреннего белого списка значений MIME-типов.