BookStack Documentation

PHP documentation & laravel repository by @BookStackApp. Model Context Protocol (MCP) server & tools with 19k stars.

18,981 stars PHP PHP 1 file · ~16,054 tokens #bookstack#documentation#laravel#php#selfhosted#wiki
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy BookStack on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name bookstack -p 8080:8080 --restart always mysql:8.4
Configured Services & Ports
⚙️ db
image: mysql:8.4
⚙️ app
image: build locally
🔌 Ports: ${DEV_PORT:-8080}:80
⚙️ node
image: node:22-alpine
⚙️ mailhog
image: mailhog/mailhog
🔌 Ports: ${DEV_MAIL_PORT:-8025}:8025
docker-compose.yml
yaml (docker-compose.yml) 
# This is a Docker Compose configuration
# intended for development purposes only

volumes:
  db: {}

services:
  db:
    image: mysql:8.4
    environment:
      MYSQL_DATABASE: bookstack-dev
      MYSQL_USER: bookstack-test
      MYSQL_PASSWORD: bookstack-test
      MYSQL_RANDOM_ROOT_PASSWORD: 'true'
    volumes:
      - ./dev/docker/init.db:/docker-entrypoint-initdb.d
      - db:/var/lib/mysql
  app:
    build:
      context: .
      dockerfile: ./dev/docker/Dockerfile
    environment:
      APP_URL: http://localhost:${DEV_PORT:-8080}
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: 3306
      DB_DATABASE: bookstack-dev
      DB_USERNAME: bookstack-test
      DB_PASSWORD: bookstack-test
      TEST_DATABASE_URL: mysql://bookstack-test:bookstack-test@db/bookstack-test
      MAIL_DRIVER: smtp
      MAIL_HOST: mailhog
      MAIL_PORT: 1025
    ports:
      - ${DEV_PORT:-8080}:80
    volumes:
      - ./:/app
      - ./dev/docker/php/conf.d/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
    entrypoint: /app/dev/docker/entrypoint.app.sh
    extra_hosts:
    - "host.docker.internal:host-gateway"
  node:
    image: node:22-alpine
    working_dir: /app
    user: node
    volumes:
      - ./:/app
    entrypoint: /app/dev/docker/entrypoint.node.sh
  mailhog:
    image: mailhog/mailhog
    ports:
      - ${DEV_MAIL_PORT:-8025}:8025

1. Project Overview & Quickstart (BookStackApp/BookStack)

File: README.md

BookStack









A platform for storing and organising information and documentation. Details for BookStack can be found on the official website at https://www.bookstackapp.com/.

📚 Project Definition

BookStack is an opinionated documentation platform that provides a pleasant and simple out-of-the-box experience. New users to an instance should find the experience intuitive and only basic word-processing skills should be required to get involved in creating content on BookStack. The platform should provide advanced power features to those that desire it, but they should not interfere with the core simple user experience.

BookStack is not designed as an extensible platform to be used for purposes that differ from the statement above.

In regard to development philosophy, BookStack has a relaxed, open & positive approach. We aim to slowly yet continuously evolve the platform while providing a stable & easy upgrade path.

You can read more about the project and its origins in our FAQ here.

🌟 Project Sponsors

Shown below are our bronze, silver and gold project sponsors.
Big thanks to these companies for supporting the project.
Note: The listed services are not tested, vetted nor supported by the official BookStack project in any manner.

Project donation details - GitHub Sponsors Page - Ko-fi Page

Gold Sponsor

Bronze Sponsors

🛠️ Development & Testing

Please see our development docs for full details regarding work on the BookStack source code.

If you're just looking to customize or extend your own BookStack instance, take a look at our Hacking BookStack documentation page for details on various options to achieve this without altering the BookStack source code.

Details about BookStack's versioning scheme and the general release process can be found here.

🌎 Translations

Translations for text within BookStack are managed through the BookStack project on Crowdin. Some strings have colon-prefixed variables such as :userName. Leave these values as they are as they will be replaced at run-time.

Please use Crowdin to contribute translations instead of opening a pull request. The translations within the working codebase can be out-of-date, and merging via code can cause conflicts & sync issues. If for some reason you can't use Crowdin feel free to open an issue to discuss alternative options.

If you'd like a new language to be added to Crowdin, for you to be able to provide translations for, please open a new issue here.

Please note, translations in BookStack are provided to the "Crowdin Global Translation Memory" which helps BookStack and other projects with finding translations. If you are not happy with contributing to this then providing translations to BookStack, even manually via code, is not advised.

🎁 Contributing, Issues & Pull Requests

Feel free to create issues to request new features or to report bugs & problems. Just please follow the template given when creating the issue.

Pull requests are welcome but, unless it's a small tweak, it may be best to open the pull request early or create an issue for your intended change to discuss how it will fit into the project and plan out the merge. Just because a feature request exists, or is tagged, does not mean that feature would be accepted into the core project.

Pull requests should be created from the development branch since they will be merged back into development once done. Please do not build from or request a merge into the release branch as this is only for publishing releases. If you are looking to alter CSS or JavaScript content please edit the source files found in resources/. Any CSS or JS files within public are built from these source files and therefore should not be edited directly.
See the Development & Testing section above for further development guidance.

The project's community rules, including those for raising issues and making code contributions, can be found here.

🔒 Security

Security information for administering a BookStack instance can be found on the documentation site here.

If you'd like to be notified of new potential security concerns you can sign-up to the BookStack security mailing list.

If you would like to report a security concern, details of doing so can be found here.

♿ Accessibility

We want BookStack to remain accessible to as many people as possible. We aim for at least WCAG 2.1 Level A standards where possible although we do not strictly test this upon each release. If you come across any accessibility issues please feel free to open an issue.

🖥️ Website, Docs & Blog

The website which contains the project docs & blog can be found in the bookstack/website repo.

⚖️ License

The BookStack source is provided under the MIT License.

The libraries used by, and included with, BookStack are provided under their own licenses and copyright.
The licenses for many of our core dependencies can be found in the attribution list below, but this is not an exhaustive list of all projects used within BookStack.

👪 Attribution

The great people that have worked to build and improve BookStack can be seen here. The wonderful people that have provided translations, either through GitHub, Codeberg or via Crowdin can be seen here.

Below are the great open-source projects used to help build BookStack.
Note: This is not an exhaustive list of all libraries and projects that would be used in an active BookStack instance.

For a detailed breakdown of the JavaScript & PHP projects imported and used via NPM & composer package managers, along with their licenses, please see the dev/licensing/js-library-licenses.txt and dev/licensing/php-library-licenses.txt files.

File: Readme.md

BookStack









A platform for storing and organising information and documentation. Details for BookStack can be found on the official website at https://www.bookstackapp.com/.

📚 Project Definition

BookStack is an opinionated documentation platform that provides a pleasant and simple out-of-the-box experience. New users to an instance should find the experience intuitive and only basic word-processing skills should be required to get involved in creating content on BookStack. The platform should provide advanced power features to those that desire it, but they should not interfere with the core simple user experience.

BookStack is not designed as an extensible platform to be used for purposes that differ from the statement above.

In regard to development philosophy, BookStack has a relaxed, open & positive approach. We aim to slowly yet continuously evolve the platform while providing a stable & easy upgrade path.

You can read more about the project and its origins in our FAQ here.

🌟 Project Sponsors

Shown below are our bronze, silver and gold project sponsors.
Big thanks to these companies for supporting the project.
Note: The listed services are not tested, vetted nor supported by the official BookStack project in any manner.

Project donation details - GitHub Sponsors Page - Ko-fi Page

Gold Sponsor

Bronze Sponsors

🛠️ Development & Testing

Please see our development docs for full details regarding work on the BookStack source code.

If you're just looking to customize or extend your own BookStack instance, take a look at our Hacking BookStack documentation page for details on various options to achieve this without altering the BookStack source code.

Details about BookStack's versioning scheme and the general release process can be found here.

🌎 Translations

Translations for text within BookStack are managed through the BookStack project on Crowdin. Some strings have colon-prefixed variables such as :userName. Leave these values as they are as they will be replaced at run-time.

Please use Crowdin to contribute translations instead of opening a pull request. The translations within the working codebase can be out-of-date, and merging via code can cause conflicts & sync issues. If for some reason you can't use Crowdin feel free to open an issue to discuss alternative options.

If you'd like a new language to be added to Crowdin, for you to be able to provide translations for, please open a new issue here.

Please note, translations in BookStack are provided to the "Crowdin Global Translation Memory" which helps BookStack and other projects with finding translations. If you are not happy with contributing to this then providing translations to BookStack, even manually via code, is not advised.

🎁 Contributing, Issues & Pull Requests

Feel free to create issues to request new features or to report bugs & problems. Just please follow the template given when creating the issue.

Pull requests are welcome but, unless it's a small tweak, it may be best to open the pull request early or create an issue for your intended change to discuss how it will fit into the project and plan out the merge. Just because a feature request exists, or is tagged, does not mean that feature would be accepted into the core project.

Pull requests should be created from the development branch since they will be merged back into development once done. Please do not build from or request a merge into the release branch as this is only for publishing releases. If you are looking to alter CSS or JavaScript content please edit the source files found in resources/. Any CSS or JS files within public are built from these source files and therefore should not be edited directly.
See the Development & Testing section above for further development guidance.

The project's community rules, including those for raising issues and making code contributions, can be found here.

🔒 Security

Security information for administering a BookStack instance can be found on the documentation site here.

If you'd like to be notified of new potential security concerns you can sign-up to the BookStack security mailing list.

If you would like to report a security concern, details of doing so can be found here.

♿ Accessibility

We want BookStack to remain accessible to as many people as possible. We aim for at least WCAG 2.1 Level A standards where possible although we do not strictly test this upon each release. If you come across any accessibility issues please feel free to open an issue.

🖥️ Website, Docs & Blog

The website which contains the project docs & blog can be found in the bookstack/website repo.

⚖️ License

The BookStack source is provided under the MIT License.

The libraries used by, and included with, BookStack are provided under their own licenses and copyright.
The licenses for many of our core dependencies can be found in the attribution list below, but this is not an exhaustive list of all projects used within BookStack.

👪 Attribution

The great people that have worked to build and improve BookStack can be seen here. The wonderful people that have provided translations, either through GitHub, Codeberg or via Crowdin can be seen here.

Below are the great open-source projects used to help build BookStack.
Note: This is not an exhaustive list of all libraries and projects that would be used in an active BookStack instance.

For a detailed breakdown of the JavaScript & PHP projects imported and used via NPM & composer package managers, along with their licenses, please see the dev/licensing/js-library-licenses.txt and dev/licensing/php-library-licenses.txt files.

File: readme.md

BookStack









A platform for storing and organising information and documentation. Details for BookStack can be found on the official website at https://www.bookstackapp.com/.

📚 Project Definition

BookStack is an opinionated documentation platform that provides a pleasant and simple out-of-the-box experience. New users to an instance should find the experience intuitive and only basic word-processing skills should be required to get involved in creating content on BookStack. The platform should provide advanced power features to those that desire it, but they should not interfere with the core simple user experience.

BookStack is not designed as an extensible platform to be used for purposes that differ from the statement above.

In regard to development philosophy, BookStack has a relaxed, open & positive approach. We aim to slowly yet continuously evolve the platform while providing a stable & easy upgrade path.

You can read more about the project and its origins in our FAQ here.

🌟 Project Sponsors

Shown below are our bronze, silver and gold project sponsors.
Big thanks to these companies for supporting the project.
Note: The listed services are not tested, vetted nor supported by the official BookStack project in any manner.

Project donation details - GitHub Sponsors Page - Ko-fi Page

Gold Sponsor

Bronze Sponsors

🛠️ Development & Testing

Please see our development docs for full details regarding work on the BookStack source code.

If you're just looking to customize or extend your own BookStack instance, take a look at our Hacking BookStack documentation page for details on various options to achieve this without altering the BookStack source code.

Details about BookStack's versioning scheme and the general release process can be found here.

🌎 Translations

Translations for text within BookStack are managed through the BookStack project on Crowdin. Some strings have colon-prefixed variables such as :userName. Leave these values as they are as they will be replaced at run-time.

Please use Crowdin to contribute translations instead of opening a pull request. The translations within the working codebase can be out-of-date, and merging via code can cause conflicts & sync issues. If for some reason you can't use Crowdin feel free to open an issue to discuss alternative options.

If you'd like a new language to be added to Crowdin, for you to be able to provide translations for, please open a new issue here.

Please note, translations in BookStack are provided to the "Crowdin Global Translation Memory" which helps BookStack and other projects with finding translations. If you are not happy with contributing to this then providing translations to BookStack, even manually via code, is not advised.

🎁 Contributing, Issues & Pull Requests

Feel free to create issues to request new features or to report bugs & problems. Just please follow the template given when creating the issue.

Pull requests are welcome but, unless it's a small tweak, it may be best to open the pull request early or create an issue for your intended change to discuss how it will fit into the project and plan out the merge. Just because a feature request exists, or is tagged, does not mean that feature would be accepted into the core project.

Pull requests should be created from the development branch since they will be merged back into development once done. Please do not build from or request a merge into the release branch as this is only for publishing releases. If you are looking to alter CSS or JavaScript content please edit the source files found in resources/. Any CSS or JS files within public are built from these source files and therefore should not be edited directly.
See the Development & Testing section above for further development guidance.

The project's community rules, including those for raising issues and making code contributions, can be found here.

🔒 Security

Security information for administering a BookStack instance can be found on the documentation site here.

If you'd like to be notified of new potential security concerns you can sign-up to the BookStack security mailing list.

If you would like to report a security concern, details of doing so can be found here.

♿ Accessibility

We want BookStack to remain accessible to as many people as possible. We aim for at least WCAG 2.1 Level A standards where possible although we do not strictly test this upon each release. If you come across any accessibility issues please feel free to open an issue.

🖥️ Website, Docs & Blog

The website which contains the project docs & blog can be found in the bookstack/website repo.

⚖️ License

The BookStack source is provided under the MIT License.

The libraries used by, and included with, BookStack are provided under their own licenses and copyright.
The licenses for many of our core dependencies can be found in the attribution list below, but this is not an exhaustive list of all projects used within BookStack.

👪 Attribution

The great people that have worked to build and improve BookStack can be seen here. The wonderful people that have provided translations, either through GitHub, Codeberg or via Crowdin can be seen here.

Below are the great open-source projects used to help build BookStack.
Note: This is not an exhaustive list of all libraries and projects that would be used in an active BookStack instance.

For a detailed breakdown of the JavaScript & PHP projects imported and used via NPM & composer package managers, along with their licenses, please see the dev/licensing/js-library-licenses.txt and dev/licensing/php-library-licenses.txt files.

2. Official Technical Reference & Guides (BookStackApp/website)

File: README.md

BookStack Site, Documentation & Blog

This project holds all the data for the https://www.bookstackapp.com/

This site is built using Hugo. Images are stored using git-lfs.
The "extended" version of hugo must be used (Has support for certain features like WebP resize).

Data Locations

  • Blog Posts - content/posts
  • Docs - content/docs
  • Theme - themes/bookstack

Hacks

The website also contains a repository of customization hacks which can be found at the /hacks part of the site.
These are managed via a separate "Hacks" repo which is part of this repository as a git submodule. A symlink is then used to point the content/hacks directory to the hacks/content directory, where hacks is the submodule location.

Theme

The theme is custom made with snippets taken from the hugo capser theme.

SCSS is used for the styling. Install NPM dependencies via npm install or yarn then you can use npm run build to build the css and site once or npm run dev to watch for changes.

Search is performed using webidx, which essentially builds a sqlite database search index, that is then loaded to browser upon search then queried locally in-browser via sql.js.

This files required are all in this repo, and hacked to suit our use-case.
The script to build the index is located at search/webidx.pl, and can be ran via the npm script

bash
npm run build:search

Note: you may need to install some dependencies to run the script see the search/webidx.pl for more information.

The above command will build the sqlite index database to static/search.db, intended to be deployed to production. There is also a npm run build:search:compress command to compress the database file using brotli and gzip (requires both to be installed). In production use, these compressed files should be deployed then served from their compressed state where possible. Here's relevant config for nginx:

nginx
location ~* \.(db)$ {
  brotli_static on;
  gzip_static on;
}

Much of the search UI handling logic can be found in our themes/bookstack/static/js/scripts.js file.

File: Readme.md

BookStack Site, Documentation & Blog

This project holds all the data for the https://www.bookstackapp.com/

This site is built using Hugo. Images are stored using git-lfs.
The "extended" version of hugo must be used (Has support for certain features like WebP resize).

Data Locations

  • Blog Posts - content/posts
  • Docs - content/docs
  • Theme - themes/bookstack

Hacks

The website also contains a repository of customization hacks which can be found at the /hacks part of the site.
These are managed via a separate "Hacks" repo which is part of this repository as a git submodule. A symlink is then used to point the content/hacks directory to the hacks/content directory, where hacks is the submodule location.

Theme

The theme is custom made with snippets taken from the hugo capser theme.

SCSS is used for the styling. Install NPM dependencies via npm install or yarn then you can use npm run build to build the css and site once or npm run dev to watch for changes.

Search is performed using webidx, which essentially builds a sqlite database search index, that is then loaded to browser upon search then queried locally in-browser via sql.js.

This files required are all in this repo, and hacked to suit our use-case.
The script to build the index is located at search/webidx.pl, and can be ran via the npm script

bash
npm run build:search

Note: you may need to install some dependencies to run the script see the search/webidx.pl for more information.

The above command will build the sqlite index database to static/search.db, intended to be deployed to production. There is also a npm run build:search:compress command to compress the database file using brotli and gzip (requires both to be installed). In production use, these compressed files should be deployed then served from their compressed state where possible. Here's relevant config for nginx:

nginx
location ~* \.(db)$ {
  brotli_static on;
  gzip_static on;
}

Much of the search UI handling logic can be found in our themes/bookstack/static/js/scripts.js file.

File: readme.md

BookStack Site, Documentation & Blog

This project holds all the data for the https://www.bookstackapp.com/

This site is built using Hugo. Images are stored using git-lfs.
The "extended" version of hugo must be used (Has support for certain features like WebP resize).

Data Locations

  • Blog Posts - content/posts
  • Docs - content/docs
  • Theme - themes/bookstack

Hacks

The website also contains a repository of customization hacks which can be found at the /hacks part of the site.
These are managed via a separate "Hacks" repo which is part of this repository as a git submodule. A symlink is then used to point the content/hacks directory to the hacks/content directory, where hacks is the submodule location.

Theme

The theme is custom made with snippets taken from the hugo capser theme.

SCSS is used for the styling. Install NPM dependencies via npm install or yarn then you can use npm run build to build the css and site once or npm run dev to watch for changes.

Search is performed using webidx, which essentially builds a sqlite database search index, that is then loaded to browser upon search then queried locally in-browser via sql.js.

This files required are all in this repo, and hacked to suit our use-case.
The script to build the index is located at search/webidx.pl, and can be ran via the npm script

bash
npm run build:search

Note: you may need to install some dependencies to run the script see the search/webidx.pl for more information.

The above command will build the sqlite index database to static/search.db, intended to be deployed to production. There is also a npm run build:search:compress command to compress the database file using brotli and gzip (requires both to be installed). In production use, these compressed files should be deployed then served from their compressed state where possible. Here's relevant config for nginx:

nginx
location ~* \.(db)$ {
  brotli_static on;
  gzip_static on;
}

Much of the search UI handling logic can be found in our themes/bookstack/static/js/scripts.js file.

File: content/donate/_index.md

title: "Donate to BookStack" url: "/donate" layout: "single" type: "about"

BookStack is Open Source software and the code & platform is provided totally without cost.
The project was started as a passion project in free time, but has grown to require a lot of time to maintain the project and support the community.
Donations provide financial support to keep time & focus on the project to help ongoing progress & development.

Donation methods

Currently, donations can be provided directly to the creator of BookStack in a couple of different ways:

  • GitHub Sponsors - Requires GitHub account.
  • Ko-fi - Supports payment via PayPal or by card (Stripe).

How are donations used?

The majority of donations cover the living costs of the project creator, Dan Brown, to allow them to focus on the project as much as possible. As of October 2021 Dan left his day-job to focus on the project; relying on savings, family-support and donations to cover living costs. Our support plans were also launched to help support finances but, at the time of writing, donations remain as the largest income source.

Some donations are effectively forwarded on to other open source projects, many of which are projects and people that BookStack depends upon itself.

Do I need to donate?

No, donations are not a requirement nor are they expected. The code and platform is provided for free under the MIT license.
Donations are an appreciated bonus and can be a straight-forward way to support development of the project, especially for businesses that save money or profit through the use of BookStack.

Do I receive anything for my donation?

Apart from our gratitude, there are no material rewards for donations unless stated within our donation options.
For example, some of the monthly sponsor options offer public display of a company's sponsorship on our website and GitHub repo.

If you could benefit from receiving assured technical support, our support plans offer a way to support the project while gaining such support benefits.

Can I support the project in a non-financial way?

Sure! We have a fairly detailed write-up on our blog regarding all the different ways that you can contribute to the project.
Check out the blogpost here.

File: content/docs/user/attachments.md

+++
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:

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:

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.

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 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.

File: content/docs/user/content-overview.md

+++
title = "Content Overview"
description = "Overview of BookStack content objects and data types"
date = "2018-09-23"
type = "user-doc"
+++

The principles of storing information within BookStack is based of the ideas of a normal stack of books. Just like normal books, BookStack books can contain chapters and pages. You start off by creating a book which acts as the highest level of categorisation. Ideally you'd have separate books for separate topics.

Within a book you can directly create pages or you can first create chapters. Chapters provide an additional level of page grouping to keep pages organised but are optional. All the information you write is held within pages. Although books and chapters do not hold information they can be given a short description to assist with searching and visibility.

Once you start to stack-up books you can start to use Bookshelves to organise your Books. Bookshelves can contain multiple books and a single book could be placed on multiple Bookshelves.

Default Colour Coding

Bookshelves, Books, chapters and pages have set colour coding in BookStack to ensure they are easily identifiable. The below examples show the default color scheme. Note that this may be overridden by your administrator.

Books
 
 
Chapters
 
 
Pages
 
 
Draft Pages
 
 
Bookshelves

Starting Out

When you start out with your new BookStack instance you can organise things in two ways; You can plan out your book/chapter/page structure or you can let things grow naturally over time. If you know or already have the content which will be going into BookStack then it's probably best to plan early otherwise, if you're starting from scratch, you'll want to let everything find its own place.

If you decide to grow naturally then you'll likely start with a book for each major category and add pages directly into those books. As you start getting a lot of pages in each book you'll start to use chapters to group those pages. Once a chapter gets too large you may find it better to split it out into its own book. Within BookStack you can easily move chapters and pages between books and chapters so you shouldn't worry about having to move things around in the future.

File: content/docs/user/diagrams.md

+++
title = "Drawings & Diagrams"
description = "Inserting and managing drawings within BookStack"
date = "2022-10-28"
type = "user-doc"
+++

BookStack has built-in support for creating and editing drawings via integrating with diagrams.net.
This integration provides very powerful drawing/diagram editing capabilities for a range of use-cases.
By default BookStack will use the online version of diagrams.net but this is configurable by an admin.

Inserting, Editing & Managing Drawings

WYSIWYG Editor

When using the WYSIWYG editor, drawings can be created & inserted into the page via a button in the editor toolbar.
The button is located in an overflow menu that's within the same section as tables and links:

To open an existing drawing for editing, simply double click on the drawing within the editor.
Alternatively you can press the toolbar drawing button while a drawing is selected.
When you edit an existing drawing and save, the new version is saved as a separate image file by BookStack, instead of overwriting existing drawings.
This is to allow proper revision history with old drawings intact.

Existing drawing files can be re-used or deleted via the drawing manager. This can be accessed via the dropdown that sits next
to the editor drawing toolbar button:

Markdown Editor

Within the markdown editor you can insert a drawing using the action found above the markdown content:

To open an existing drawing for editing, just double click the image within the preview window and the existing drawing should be
opened for editing.
When you edit an existing drawing and save, the new version is saved as a separate image file by BookStack, instead of overwriting existing drawings.
This is to allow proper revision history with old drawings intact.

Drawing Image File Storage & Format

Drawings files created via the diagrams.net integration are saved to your own BookStack system, using the same storage mechanism as configured for normal images.

For portability & compatibility, drawings are saved in PNG file format, with the original diagrams.net drawing data embedded within.
Since the drawing data is embedded with the PNG image file, you can continue editing such drawings in any diagrams.net instance just by dragging-in or
importing the image file.

File: content/docs/user/getting-around.md

+++
title = "Getting Around and Finding Content"
date = "2022-12-12"
type = "user-doc"
slug = "getting-around"
+++

There are many ways to get around and find content within your BookStack instance
outside of following the core hierarchy. Below is an overview of some common options.

{{}}

Book Sidebar

The book sidebar is visible when within a book, and it reflects the full ordered hierarchy
of the book you are within. If you are within a chapter, that chapter will be expanded by
default otherwise they will be collapsed, and expandable with a click.

When viewing a page or chapter, you'll find links below the main content that allow you to
navigate between the next & previous content within the current book.
These links will reflect sibling content, or the next item within the parent level if no adjacent content exists.

As you dive into your BookStack content you'll see breadcrumbs above
the main content area to reflect the parent path of the current item.
These will begin with the "Books" page unless
you've traveled through the "Shelves" view in which case this would begin with
the "Shelves" view and parent shelf.

You can click on breadcrumb items to navigate directly to those. You can also click the
arrows between items to search and jump to orthogonal content within
the structure hierarchy.

A major way to find and jump to content is by using search.
There's the global search input in the header, where you can search across all content in your instance:

When you start a global search, you'll get live feedback showing a preview of search results.
You can press enter or "View All" to view all relevant results on the search page.
Within the book and chapter views, you'll also find search inputs allowing you to search just within that book or chapter.

Find more information on our "Searching Content" page.

Activity Lists

Many views, like that for a book or on the homepage, will show a list of
"Recent Activity", reflecting recent actions that have been made relevant to the
current context.
On these, you can click the name of the item within the listed activity to jump to that item.

Recently Updated List

On the homepage you can find a "Recently Updated" list, showing the latest pages
to have been created or updated.
You can press "View All" to view a larger paginated list.

Favourites

One way to easily recall content is by adding it to your favourites.
You can choose to favourite any shelf, book, chapter or page to add it
to your personal favourite collection.
You can then easily find your favourites either as a list on the homepage
or via the "My Favourites" link in the header profile dropdown.

File: content/docs/user/markdown-editor.md

+++
title = "Markdown Editor"
description = "Details on using the markdown editor in BookStack"
date = "2017-07-28"
type = "user-doc"
+++

If you prefer to write in a simpler format, a Markdown editor is available in BookStack. Markdown compatibility generally follows that of CommonMark, along with a few extensions including tables and task-lists.
This is an alternative to the default WYSIWYG Editor.

Switching to the Markdown Editor

The default editor option, for when creating a new page, can be configured by an admin within the "Settings > Customization" area of BookStack.

You can change to the markdown editor at a page-level while within the page editor.
Simply click the draft status, located above the page name input, and you'll be presented a drop-down with options which include those to change the editor. If you don't see these options, you may not have the relevant "Change page editor" system permission on one of your assigned system roles.

For switching to Markdown, from the WYSIWYG editor, you'll see a couple of options:

  • Clean Content - This is a system-cleaned markdown output, which is much nicer but has potential for formatting loss and potential functionality breaks (Things depending on HTML attributes/IDs for example).
  • Stable Content - This retains existing HTML content in Markdown to avoid any potential functionality breakages or loss of formatting.

When you choose either option, there is risk of losing certain content details or formatting. BookStack will warn you of this when switching.

Editor Shortcuts

The following shortcuts are available in the Markdown Editor:

Shortcut (Windows & Linux/Mac) Description
Ctrl+S / Cmd+S Save Draft
Ctrl+Enter / Cmd+Enter Save Page & Continue
Ctrl+1 / Cmd+1
text
`Ctrl+2` / `Cmd+2` 
    `Ctrl+3` / `Cmd+3` 
    `Ctrl+4` / `Cmd+4` | Header Large (h2)
    Header Medium (h3)
    Header Small (h4)
    Header Tiny (h5) |

| Ctrl+5 / Cmd+5``Ctrl+D / Cmd+D | Normal Paragraph |
| Ctrl+6 / Cmd+6``Ctrl+Q / Cmd+Q | Blockquote |
| Ctrl+7 / Cmd+7``Ctrl+E / Cmd+E | Code Block |
| Ctrl+8 / Cmd+8``Ctrl+Shift+E / Cmd+Shift+E | Inline Code |
| Ctrl+9 / Cmd+9 | Callout *(Keep pressing to toggle through styles)* |
| Ctrl+O / Cmd+O
Ctrl+P / Cmd+P | Ordered List Bullet List |
| Ctrl+K / Cmd+K | Insert Link |
| Ctrl+Shift+K / Cmd+Shift+K | Link to BookStack content |
| Ctrl+Shift+I / Cmd+Shift+I | Insert Image via URL |

File: content/docs/user/organising-content.md

+++
title = "Organising Content"
description = "How to organise and sort books, chapters and pages in BookStack"
date = "2017-01-01"
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.

Moving Single Pages & Chapters

Pages and chapters can be moved directly to a new chapter or book. To move a chapter or page in this way, go to a page or chapter and select 'Move' in the actions list:

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.

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.

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.

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.

Keep in mind that a book can be on multiple shelves, so adding a book to a new shelf won't cause it to be removed from any others. If you want to remove a book from a shelf you'll need to go into each shelf in the same manner as above but select, or drag them out, from the "Books on this shelf" list before saving.

File: content/docs/user/page-permalinks.md

+++
title = "Page Permalinks"
date = "2020-01-24"
type = "user-doc"
slug = "content-permalinks"
+++

The URL for a page within BookStack includes a "Slug" generated based upon the name in addition to a "Slug" generated from the parent book's name. Upon name changes of the book or page, BookStack will use the revision system to attempt resolving when old links are used but it is possible for some actions to cause old page links to no longer lead to the updated content.

The below details how you can find an id-based page link for scenarios where you want to be sure of a stable link.

Finding the Page Permalink

A quick and easy way to find the page Permalink has been built into BookStack.
Simply select any block of text within a page and you'll see a small popup box. Within this popup box will be an input containing the page permalink. A copy button next to the input allows you to copy the link with a single click.

By default this link will include a # component so that the URL scrolls the page to the specific selected section. If you don't want this, and instead want the link to just lead to the page and not scroll down, you can remove the # and everything after it within the link you copied.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#bookstack Browse bookstack catalog → #documentation Browse documentation catalog → #laravel Browse laravel catalog → #php Browse php catalog → #selfhosted Browse selfhosted catalog → #wiki Browse wiki catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →