From: Dan Brown Date: Fri, 20 Dec 2024 18:50:12 +0000 (+0000) Subject: Performed docs updates for v24.12, added import/export page X-Git-Url: http://source.bookstackapp.com/website/commitdiff_plain/744833a680967620bfcc673158c38ca59435611e Performed docs updates for v24.12, added import/export page --- diff --git a/content/blog/2024/bookstack-release-v24-12.md b/content/blog/2024/bookstack-release-v24-12.md index 8a4933a..6c87e3e 100644 --- a/content/blog/2024/bookstack-release-v24-12.md +++ b/content/blog/2024/bookstack-release-v24-12.md @@ -17,6 +17,10 @@ new import & export format, while improving upon the new editor introduced in th TODO - Peertube +**Upgrade Notices** + +- **Requirements Change** - The "zip" PHP extension is now a requirement for BookStack. If you installed via our Ubuntu scripts, this should already be installed. + ### New Importable Export Format A new export option is now available for books, chapters & pages: "Portable ZIP" diff --git a/content/docs/admin/email-webhooks.md b/content/docs/admin/email-webhooks.md index c3d196c..927c5e7 100644 --- a/content/docs/admin/email-webhooks.md +++ b/content/docs/admin/email-webhooks.md @@ -86,6 +86,12 @@ MAIL_SENDMAIL_COMMAND="/usr/sbin/sendmail -bs" #### Debugging Email +Failed email sends are handled differently depending on what triggers them. +In some cases, like for user invites, an error will be shown to the user within BookStack since the email +is required to perform the intended action. +In other cases, like user activity/watch notification emails, failure of email send will not be shown +to the BookStack user performing activity, but the error will just be logged to the application error log file. + You can follow the instructions provided in the [debugging documentation page](/docs/admin/debugging/) to help gain more details about issues you may come across. Within the "Settings > Maintenance" area of BookStack you can find a "Send a Test Email" action which provides a quick & easy way to send emails diff --git a/content/docs/admin/installation.md b/content/docs/admin/installation.md index e7ff09c..ddfb4cd 100644 --- a/content/docs/admin/installation.md +++ b/content/docs/admin/installation.md @@ -29,7 +29,7 @@ BookStack has the following core requirements: * **PHP** >= 8.1 * For installation and maintenance, you'll need to be able to run `php` from the command line. - * Required Extensions: gd, dom, iconv, mbstring, mysqlnd, openssl, pdo, pdo_mysql, tokenizer, xml. + * Required Extensions: gd, dom, iconv, mbstring, mysqlnd, openssl, pdo, pdo_mysql, tokenizer, xml, zip. * Optional Extensions: ldap *(If wanting to use LDAP Auth)*. * *For PHP MySQL extensions use `nd` (Native Driver) variants where provided, otherwise these may be the default provided in modern `mysql` PHP extension packages.* * **MySQL** >= 5.7 or **MariaDB** >= 10.2 diff --git a/content/docs/admin/ldap-auth.md b/content/docs/admin/ldap-auth.md index 3f3f09c..d28f46b 100644 --- a/content/docs/admin/ldap-auth.md +++ b/content/docs/admin/ldap-auth.md @@ -51,7 +51,10 @@ LDAP_ID_ATTRIBUTE=uid # Set the default 'email' attribute. Defaults to 'mail' LDAP_EMAIL_ATTRIBUTE=mail -# Set the property to use for a user's display name. Defaults to 'cn' +# Set the property to use for a user's display name. Defaults to 'cn'. +# Can have multiple attributes listed, separated with a '|' in which +# case those values will be joined with a space. +# Example: LDAP_DISPLAY_NAME_ATTRIBUTE=given_name|family_name LDAP_DISPLAY_NAME_ATTRIBUTE=cn # Set the attribute to use for the user's avatar image. diff --git a/content/docs/admin/updates.md b/content/docs/admin/updates.md index 4720ce7..0603d51 100644 --- a/content/docs/admin/updates.md +++ b/content/docs/admin/updates.md @@ -41,6 +41,9 @@ This is primarily a list of breaking changes & security notices. Details of updates can be found on [our blog](https://www.bookstackapp.com/blog/) or via the [GitHub releases page](https://github.com/BookStackApp/BookStack/releases). +#### Updating to v24.12 or higher + +**Requirements Change** - The "zip" PHP extension is now a requirement for BookStack. If you installed via our Ubuntu scripts, this should already be installed. #### Updating to v24.10.2 or higher diff --git a/content/docs/user/export-import.md b/content/docs/user/export-import.md new file mode 100644 index 0000000..3d9aa79 --- /dev/null +++ b/content/docs/user/export-import.md @@ -0,0 +1,51 @@ ++++ +title = "Exporting & Importing Content" +date = "2024-12-20" +type = "user-doc" ++++ + +BookStack allows its content to be exported in a range of formats, while also providing +a few options for importing content. +Note that these option are not intended for backup or restore, for which you [can find relevant documentation here](/docs/admin/backup-restore/). + +### Exporting + +Within BookStack, if you have the required "Export content" role permission, you can export books, +chapters or pages in the following formats: + +- Contained Web File + - A ".html" file with images embedded where possible, which can be opened in a browser. + - This usually provides the best representation of your BookStack content. +- PDF File + - A ".pdf" document file representation of your content. + - The output of this can sometimes be inaccurate or lack certain features compared to how its represented in BookStack. +- Plain Text File + - A ".txt" file with just the text containing in your content. +- Markdown File + - A ".md" file with a markdown representation of your content. + - If the page was written using the Markdown editor, then that original content will be provided otherwise this export will attempt a conversion to Markdown. + - The resulting markdown may still use HTML for some content types. +- Portable ZIP + - A ".zip" containing data, attachment and image files. + - This can be re-imported to BookStack instances as mentioned below. + - The exact format can be found documented [in the BookStack source here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/portable-zip-file-format.md). + +Although not shown as an export format, care is taken in BookStack to ensure that pages display well via browser printing options. +This allows you to print to paper, or often to PDF, via your browser's print action as another form of export. + +For developers, many of these export options can also be accessed over the [BookStack REST API](/docs/admin/hacking-bookstack/#bookstack-api), which +also provides many other endpoints that may be found useful for export-focused tasks. + +### Importing + +Within BookStack, if you have the required "Import content" role permission, you can import "Portable ZIP" +files (as mentioned in the [exporting](#exporting) section above) via the "Import" action seen when viewing the +top-level "Books" view, or by going to the `/import` URL path of your instance: + +View of the import page, with a field to select a ZIP for upload, and a section below showing "Pending Imports" with one "IT Department" book listed + +Here you'll be able to upload a new ZIP file for import, or continue a previously uploaded pending import. +Before the import runs, you'll be provided a preview of what's due to be imported. +When ran, the content will be imported into BookStack, and the original uploaded ZIP file will be deleted. + +For developers, the details of this importable ZIP format [can be found here](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/portable-zip-file-format.md) otherwise you could also consider the [BookStack REST API](/docs/admin/hacking-bookstack/#bookstack-api) as an option for import. \ No newline at end of file diff --git a/static/images/docs/user/import-overview.png b/static/images/docs/user/import-overview.png new file mode 100644 index 0000000..650fd61 --- /dev/null +++ b/static/images/docs/user/import-overview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:521ab395b54c25722e1b8b0f320d9d91fe66354411fc613cf43f4844ef282873 +size 38369 diff --git a/themes/bookstack/layouts/partials/menu_user_docs.html b/themes/bookstack/layouts/partials/menu_user_docs.html index b00bd4d..dac2a68 100644 --- a/themes/bookstack/layouts/partials/menu_user_docs.html +++ b/themes/bookstack/layouts/partials/menu_user_docs.html @@ -15,6 +15,7 @@
  • Markdown Editor
  • Attachments
  • Drawings & Diagrams
    • +
  • Exporting & Importing