bookstack/website
Fork 4
Code Issues 5 Pull requests Activity

Finished up v0.25 docs with a bit of a re-org

Browse source 
- Updated gulp to use latest libs. - Added upload configuration page and moved existing upload related docs into it. - Added misc docs for extra bits. - Re-organised sidebar. - Spaced out sidebar items and made sticky on desktop.
This commit is contained in:
Dan Brown 2019-01-12 22:19:01 +00:00
commit f67775c6da
Signed by: danb
GPG key ID: 46D9F943C24A2EF9
13 changed files with 3960 additions and 1591 deletions
Download patch file Download diff file Expand all files Collapse all files

27
content/docs/admin/language-config.md
View file

@ -23,21 +23,24 @@ APP_LANG=fr
The value of the `APP_LANG` variable must be a valid locale code matching one of the following options:
* English - `en`
* German - `de`
* Spanish - `es`
* Spanish, Argentinian - `es_AR`
* French - `fr`
* Dutch - `nl`
* Brazilian Portuguese - `pt_BR`
* Slovakian - `sk`
* Swedish - `sv`
* Japanese - `ja`
* Polish - `pl`
* Italian - `it`
* Russian - `ru`
* Chinese (Simplified) - `zh_CN`
* Chinese (Traditional) - `zh_TW`
* Dutch - `nl`
* English - `en`
* French - `fr`
* German (Formal) - `de`
* German (Informal) - `de_informal`
* Italian - `it`
* Japanese - `ja`
* Korean - `kr`
* Polish - `pl`
* Russian - `ru`
* Slovakian - `sk`
* Spanish - `es`
* Spanish, Argentinian - `es_AR`
* Swedish - `sv`
* Ukrainian - `uk`
### Public User Locale Autodetection

12
content/docs/admin/ldap-auth.md
View file

@ -21,10 +21,8 @@ AUTH_METHOD=ldap
LDAP_SERVER=example.com:389
# If using LDAP over SSL you should also define the protocol:
# LDAP_SERVER=ldaps://example.com:636
# To allow untrusted LDAPS certificates, define the following:
# LDAP_TLS_INSECURE=true
# The base DN from where users will be searched within.
# The base DN from where users will be searched within
LDAP_BASE_DN=ou=People,dc=example,dc=com
# The full DN and password of the user used to search the server
@ -36,11 +34,15 @@ LDAP_PASS=false
# The user-provided user-name used to replace any occurrences of '${user}'
LDAP_USER_FILTER=(&(uid=${user}))
# Set the LDAP version to use when connecting to the server.
# Set the LDAP version to use when connecting to the server
LDAP_VERSION=false
# Set the default 'email' attribute. Defaults to 'mail'.
# Set the default 'email' attribute. Defaults to 'mail'
LDAP_EMAIL_ATTRIBUTE=mail
# If you need to allow untrusted LDAPS certificates, add the below and uncomment (remove the #)
# Only set this option if debugging or you're absolutely sure it's required for your setup.
#LDAP_TLS_INSECURE=true
```
You will also need to have the php-ldap extension installed on your system. It's recommended to change your `APP_DEBUG` variable to `true` while setting up LDAP to make any errors visible. Remember to change this back after LDAP is functioning.

60
content/docs/admin/other-config.md Normal file
View file

@ -0,0 +1,60 @@
+++
title = "Other Configuration"
description = "Other BookStack configuration such as system revisions and custom avatar fetching"
date = "2018-01-12"
type = "admin-doc"
+++
* [.env Options](#env-options)
* [Revision Limit](#revision-limit)
* [Custom User Avatar Fetching](#custom-user-avatar-fetching)
---
### .env Options
As part of the installation of BookStack you will have a `.env` file containing system options. By default this only contains a few options.
Within your BookStack install directory you should also have a `.env.example.complete` file which contains every support option available alongside the default value for each.
You can copy options in this file to your own `.env` file as required. Many of the options in the `.env.example.complete` file are detailed in-depth in this documentation.
The `.env` file essential sets environment variables for BookStack to read. Environment variables will be checked if an option is not in the `.env` file which can be useful
in the creation and use of docker containers.
---
### Revision Limit
Each time a page is saved a revision is stored to track history. To prevent your database becoming bloated BookStack will automatically remove revisions when the count, per page, exceeds 50. You can set the following option in your `.env` file to increase or remove the limit:
```bash
# Set the revision limit to 100
# Defaults to '50'
REVISION_LIMIT=100
# Alternatively, You can set to 'false' to disable the limit altogether.
REVISION_LIMIT=false
```
---
### Custom User Avatar Fetching
When a user is created BookStack will, by default, fetch an avatar image from [Gravatar](https://en.gravatar.com/). This functionality can be disabled or the URL can be customized
which allows you to use a different avatar service altogether. Examples of this can be seen below:
```bash
# In your .env file
# Use libravatar instead of gravatar
AVATAR_URL=https://seccdn.libravatar.org/avatar/${hash}?s=${size}&d=identicon
# Disable avatar fetching altogether
AVATAR_URL=false
```
The following variables can be used in this setting which will be populated by BookStack when used:
* `${email}` - The user's email address, URL encoded.
* `${hash}` - MD5 hashed copy of the user's email address.
* `${size}` - BookStack's ideal requested image size in pixels.

9
content/docs/admin/updates.md
View file

@ -30,6 +30,15 @@ Check the below list for the version you are updating to for any additional inst
## Version Specific Instructions
#### Updating to v0.25 or higher
**Security** - During the release cycle for Version v0.25 it was found that page content includes could leak their content as preview text to users that don’t have permission to view the included content. It’s recommended to re-save any pages that included other page content that’s restricted to ensure included text is not shown in page preview text.
**Requirements Change** - Minimum required version of PHP has changed from 7.0.0 to 7.0.5.
**Configuration Change** - The .env option `GRAVATAR_URL=false` has been replaced by `AVATAR_URL=false`.
#### Updating to v0.24 or higher
Version v0.24 changes the way the homepage option is stored. After updating, You may need to re-configure this setting.

140
content/docs/admin/upload-config.md Normal file
View file

@ -0,0 +1,140 @@
+++
title = "Configuring File Uploads"
description = "Configuration for files uploads such as images and attachments"
date = "2018-01-12"
type = "admin-doc"
+++
BookStack allows users to upload both images for content and files as attachments.
* [Storage Options](#storage-options)
* [Changing Upload Limits](#changing-upload-limits)
* [File Upload Timeout](#file-upload-timeout)
**For information relating to security for file uploads please refer to the [Security Page](/docs/admin/security).**
---
### Storage Options
Within BookStack there are a few different options for storing files:
* **local** (Default) - Files are stored on the server running BookStack. Images are publically accessible, served by your websever, but attachments are secured behind BookStack's authentication.
* **local_secure** - Same as local option but images are served by BookStack, enabling authentication on image requests. Provides higher security but is more system resource intensive and could induce performance issues.
* **s3** - Store files externally on Amazon S3. Images are made publically accessible on upload.
For all options you can use the 'Enable higher security image uploads' in-app admin setting which appends a random string to each uploaded image name to make URL's hard to guess.
#### Local
This is the default storage mechanism in BookStack. It can be forced by setting the following in your `.env` file:
```bash
STORAGE_TYPE=local
```
* Image uploads location: `<bookstack_install_dir>/public/uploads/images`.
* Attachment uploads location: `<bookstack_install_dir>/storage/uploads/files`.
#### Local (Secure)
The local secure option can be enabled by setting the following in your `.env` file:
```bash
STORAGE_TYPE=local_secure
```
After setting this option ensure you test system performance creating a page with many images and reload on that page multiple times to ensure your server can keep with the
multitude of image requests.
* Image uploads location: `<bookstack_install_dir>/storage/uploads/images`.
* Attachment uploads location: `<bookstack_install_dir>/storage/uploads/files`.
If you'd like to switch to this option from the default `local` storage system you'll first need to migrate existing image uploads to the image folder listed above.
#### S3
The Amazon s3 option can be enabled by setting the following in your `.env` file:
```bash
STORAGE_TYPE=s3
STORAGE_S3_KEY=your-s3-key
STORAGE_S3_SECRET=your-s3-secret
STORAGE_S3_BUCKET=s3-bucket-name
STORAGE_S3_REGION=s3-bucket-region
```
For performance reasons uploaded images are made public upon upload to your s3 bucket and fetched directly by the end user when viewing an image on BookStack. Attachments are not made public and are instead fetched by BookStack upon request. Exact security will depend on the configuration and policies of your bucket.
* Image uploads location: `<your_bucket>/uploads/images`.
* Attachment uploads location: `<your_bucket>/uploads/files`.
By default BookStack will generate a valid Amazon S3 URL for uploaded images. If you'd prefer to use a different URL, that you have pointed at your bucket, you can add the below option to your `.env` file which will be used as a base URL for all image uploads:
```bash
STORAGE_URL=https://images.example.com
```
---
### Changing Upload Limits
By default, a lot of server software has strict limits on upload sizes which causes errors when users upload new content. This is not configured as part of BookStack but as part of PHP and your web sever software. If you run into problems with upload size limits follow the below details for PHP and whichever web server you use:
#### PHP
PHP has two main variables which effect upload limits. Find your `php.ini` file and look for the following variables:
* `post_max_size`
* `upload_max_filesize`
If the values of these variables are low increase them to something sensible that's not too high to cause issues. Unless you need something higher 10MB is a sensible value to enter for these values:
```
post_max_size = 10M
upload_max_filesize = 10M
```
After updating these values ensure you restart your webserver and also PHP if using PHP-FPM or something similar.
#### NGINX
By default NGINX has a limit of 1MB on file uploads. To change this you will need to set the `client_max_body_size` variable. You can do this either in the http block in your `nginx.conf` file or in the server block set up for BookStack. Here's an example of increasing the limit it 10MB in the http block:
```nginx
http {
#...
client_max_body_size 100m;
client_body_timeout 120s; # Default is 60, May need to be increased for very large uploads
#...
}
```
As per the example above, If you are expecting upload very large files where upload times will exceed 60 seconds you will also need to add the `client_body_timeout` variable with a large value.
After updating you NGINX configuration don't forget to restart NGINX. You can test the configuration beforehand with `nginx -t`.
#### Apache
Apache does not have any built-in limits which you will need to change but something to note is that if you are using apache and mod_php with `.htaccess` files enabled you may be able to set the above PHP variables in your `.htaccess` file like so:
```apache
php_value upload_max_filesize 10M
php_value post_max_size 10M
```
---
### File Upload Timeout
File uploads in BookStack use a JavaScript library which has a default upload timeout of 60 seconds. This means that if the file that you are uploading does not upload completely to the server within 60 seconds, the system will timeout.
To modify this timeout, in BookStack settings, Find the 'Custom HTML head content' setting and add the below code. Note that this does not change any server-side upload limits, Your websever may still impose an upload limit.
```html
<script>
// Set the file upload timeout to 120 seconds.
// You can change '120' to be the number of seconds you want the timeout to be.
window.uploadTimeout = 120 * 1000;
</script>
```

56
content/docs/admin/upload-limits.md
View file

@ -1,56 +0,0 @@
+++
title = "Changing Upload Limits"
description = "How to increase uploads limits for images and attachments"
date = "2017-01-01"
type = "admin-doc"
+++
BookStack allows users to upload both images for content and files as attachments. By default, a lot of server software has strict limits on upload sizes which causes errors when users upload new content. This is not configured as part of BookStack but as part of PHP and your web sever software. If you run into problems with upload size limits follow the below details for PHP and whichever web server you use:
---
### PHP
PHP has two main variables which effect upload limits. Find your `php.ini` file and look for the following variables:
* `post_max_size`
* `upload_max_filesize`
If the values of these variables are low increase them to something sensible that's not too high to cause issues. Unless you need something higher 10MB is a sensible value to enter for these values:
```
post_max_size = 10M
upload_max_filesize = 10M
```
After updating these values ensure you restart your webserver and also PHP if using PHP-FPM or something similar.
---
### NGINX
By default NGINX has a limit of 1MB on file uploads. To change this you will need to set the `client_max_body_size` variable. You can do this either in the http block in your `nginx.conf` file or in the server block set up for BookStack. Here's an example of increasing the limit it 10MB in the http block:
```nginx
http {
#...
client_max_body_size 100m;
client_body_timeout 120s; # Default is 60, May need to be increased for very large uploads
#...
}
```
As per the example above, If you are expecting upload very large files where upload times will exceed 60 seconds you will also need to add the `client_body_timeout` variable with a large value.
After updating you NGINX configuration don't forget to restart NGINX. You can test the configuration beforehand with `nginx -t`.
---
### Apache
Apache does not have any built-in limits which you will need to change but something to note is that if you are using apache and mod_php with `.htaccess` files enabled you may be able to set the above PHP variables in your `.htaccess` file like so:
```apache
php_value upload_max_filesize 10M
php_value post_max_size 10M
```

24
content/docs/admin/visual-customisation.md
View file

@ -1,5 +1,5 @@
+++
title = "Customising BookStack"
title = "Customising Visuals"
description = "Changing the colors, logo and styles of BookStack to suit your needs"
date = "2017-08-22"
type = "admin-doc"
@ -71,28 +71,6 @@ APP_VIEWS_BOOKS=grid
APP_VIEWS_BOOKS=list
```
### Revision Limit
Each time a page is saved a revision is stored to track history. To prevent your database becoming bloated BookStack will automatically remove revisions when the count, per page, exceeds 50. You can set the following option in your `.env` file to increase or remove the limit:
```bash
# Set the revision limit to 100
# Defaults to '50'
REVISION_LIMIT=100
# Alternatively, You can set to 'false' to disable the limit altogether.
REVISION_LIMIT=false
```
### File upload timeout
File uploads in BookStack use a plugin called DropzoneJS. DropzoneJS is configured with a default upload timeout of 60 seconds. This means that if the file that you are uploading does not upload completely to the server within 60 seconds, the system will timeout.
To modify this timeout, in BookStack settings, Find the 'Custom HTML head content' setting and add the following code:
```js
window.uploadTimeout = 30000 // To set the timeout to 30 seconds
```
### Further Customisation
If you need to customise BookStack further to the given controls in the settings area you can make use of the 'Custom HTML head content' setting. Using this you can add in any custom JavaScript or CSS content to override default BookStack functionality and styles.

20
gulpfile.js
View file

@ -1,12 +1,12 @@
var gulp = require('gulp'),
plumber = require('gulp-plumber'),
rename = require('gulp-rename');
var autoprefixer = require('gulp-autoprefixer');
var minifycss = require('gulp-minify-css');
var sass = require('gulp-sass');
const gulp = require('gulp');
const plumber = require('gulp-plumber');
const rename = require('gulp-rename');
const autoprefixer = require('gulp-autoprefixer');
const minifycss = require('gulp-minify-css');
const sass = require('gulp-sass');
gulp.task('styles', function(){
gulp.src(['themes/bookstack/sass/**/*.scss'])
gulp.task('styles', function() {
return gulp.src(['themes/bookstack/sass/**/*.scss'])
.pipe(plumber({
errorHandler: function (error) {
console.log(error.message);
@ -21,8 +21,8 @@ gulp.task('styles', function(){
});
gulp.task('default', ['styles']);
gulp.task('default', gulp.series('styles'));
gulp.task('watch', function() {
gulp.watch('themes/bookstack/sass/**/*.scss', ['styles']);
gulp.watch('themes/bookstack/sass/**/*.scss', gulp.series('styles'));
});

5166
package-lock.json generated
View file

File diff suppressed because it is too large Load diff

10
package.json
View file

@ -12,12 +12,12 @@
"author": "Dan Brown",
"license": "MIT",
"devDependencies": {
"gulp": "3.9.1",
"gulp-autoprefixer": "4.0.0",
"gulp": "4.0.0",
"gulp-autoprefixer": "6.0.0",
"gulp-minify-css": "1.2.4",
"gulp-plumber": "1.1.0",
"gulp-rename": "1.2.2",
"gulp-sass": "3.1.0"
"gulp-plumber": "1.2.1",
"gulp-rename": "1.4.0",
"gulp-sass": "4.0.2"
},
"dependencies": {}
}

10
themes/bookstack/layouts/_default/single.html
View file

@ -25,12 +25,14 @@
<div class="row">
<div class="col-sm-2 sidebar">
{{ if eq .Type "admin-doc" }}
<div class="sidebar-inner">
{{ if eq .Type "admin-doc" }}
{{partial "menu_admin_docs"}}
{{end}}
{{ if eq .Type "user-doc" }}
{{end}}
{{ if eq .Type "user-doc" }}
{{partial "menu_user_docs"}}
{{end}}
{{end}}
</div>
</div>
<div class="col-sm-8 col-sm-offset-1 docs-content">

5
themes/bookstack/layouts/partials/menu_admin_docs.html
View file

@ -1,9 +1,7 @@
<h4>Setup</h4>
<ul>
<li><a href="/docs/admin/installation">Installation</a></li>
<li><a href="/docs/admin/visual-customisation">Branding &amp; Customisation</a></li>
<li><a href="/docs/admin/security">Security</a></li>
<li><a href="/docs/admin/upload-limits">Changing Upload Limits</a></li>
<li><a href="/docs/admin/multi-instance">Multiple Instances</a></li>
<li><a href="/docs/admin/subdirectory-setup">Subdirectory Setup</a></li>
</ul>
@ -18,10 +16,13 @@
<h4>Configuration</h4>
<ul>
<li><a href="/docs/admin/visual-customisation">Visual Customisation</a></li>
<li><a href="/docs/admin/language-config">Language &amp; Locale</a></li>
<li><a href="/docs/admin/upload-config">File Uploads</a></li>
<li><a href="/docs/admin/cache-session-config">Caching &amp; Sessions</a></li>
<li><a href="/docs/admin/social-auth">Third Party Authentication</a></li>
<li><a href="/docs/admin/ldap-auth">LDAP Authentication</a></li>
<li><a href="/docs/admin/pdf-rendering">PDF Rendering</a></li>
<li><a href="/docs/admin/ut8mb4-support">UTF8mb4/Emoji Support</a></li>
<li><a href="/docs/admin/other-config">Other Configuration</a></li>
</ul>

12
themes/bookstack/sass/styles.scss
View file

@ -294,12 +294,24 @@ input[type=text] {
list-style: none;
margin-left: 0;
}
li {
padding: 2px 0;
}
}
.sidebar {
border-right: 2px dotted #E5E5E5;
}
@include larger-than($xl) {
.sidebar {
position: sticky;
top: $-m;
}
}
h2.thin-margin {
margin-top: 0;
}