BookStack 用户指南

官方用户文档示例（英文）

Attachments

来源：BookStack 官方文档（开源）。原图外链已省略。

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"]

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]

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

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.

Content Overview

来源：BookStack 官方文档（开源）。原图外链已省略。

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.

Drawings & Diagrams

来源：BookStack 官方文档（开源）。原图外链已省略。

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:

[图片：View of the WYSWIYG editor toolbar with the drawing button highlighted]

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:

[图片：Drawing managed popup view showing a grid of drawing thumbnails]

Markdown Editor

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

[图片：View of the Markdown editor with an "Insert Drawing" action highlighted]

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.

Getting Around and Finding Content

来源：BookStack 官方文档（开源）。原图外链已省略。

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.

[图片：View of the book sidebar showing child chapters and pages]

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.

[图片：View of the next & previous actions when viewing a page]

Breadcrumbs

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.

[图片：View of BookStack items, in a hierarchy, with arrows in between]

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.

[图片：Breadcrumb view with an arrow clicked, showing a popover element listing BookStack pages and chapters]

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:

[图片：View of the header search bar with a search started and relevant items listed]

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.

[图片：A list of user activity showing linked items names]

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.

[图片：A card section with title "Recently Updates Pages" with a list of pages below]

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.

[图片：A view of the "My Favourites" page, with the header profile dropdown menu showing containing a link to "My Favourites"]

Markdown Editor

来源：BookStack 官方文档（开源）。原图外链已省略。

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.

[图片：Editor Switch Menu Options]

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

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

Organising Content

来源：BookStack 官方文档（开源）。原图外链已省略。

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:

Page Move Action

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.

[图片：Book Sort]

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.

[图片：Adding or removing books on a 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.

Page Templates

来源：BookStack 官方文档（开源）。原图外链已省略。

Within BookStack you can mark a page as a template so that its content can easily be reused when editing and creating pages. This can be super useful when you need to create many pages following a similar format.

Creating a Page Template

A page template in BookStack is simply a normal page that has been marked as a template. Start by creating/editing the page you want to use as a template. Within the editor sidebar you should see a templates tab. Within this tab you should find a "Page is a template" checkbox. Simply check that option and save the page to make the page become a template. If you don't see that checkbox, you likely lack the "Manage page templates" role system permission.

[图片：Page edit view showing the templates tab and mentioned checkbox]

Note: Visibility of page templates are controlled via visibility of the page itself. If a user lacks permission to view the page marked as a template, it will not show as an available template for them.

Using Page Templates

Page templates can be accessed when creating or editing a page. Within the editor sidebar you should see a templates tab. If you have templates available they will be listed in this area. A search bar will also show for easy searching of templates.

There are multiple ways to add a template into a page:

[图片：Dragging a template into the page editor]

Keep in mind that using a template simply copies its content at time-of-use, it is not a "live" connection to the template page, and updating the template page won't affect pages that have previously used it as a template.

Default Page Templates

If you'd like to always start a new page with a specific template, this can be configured at a per-book level using the "Default Page Template" option when editing a book:

[图片：Dragging a template into the page editor]

With this option set, the selected template will be used to pre-fill the contents of any new page created within that book. Like with other template usages, access to the template will be controlled by permissions. If a user creates a page with the book, but does not have access to view the template page, it will not be used to pre-fill the contents of the new page.

Reusing Page Content

来源：BookStack 官方文档（开源）。原图外链已省略。

Within BookStack you may find that you want to include the same block of content in multiple places. You could copy and paste that content into multiple pages but then, if that content needs to be changed, you'd have to update it multiple times across different pages. By using include tags you can include entire other pages and also include single blocks of content from other pages.

Considerations

Here are some things to consider when reusing page content via include tags:

Include Tags

To include the content of a page within another you can use the following syntax:

{{@page_id}} or {{@page_id#content_id}}

Here are some examples of this in use:

You simply enter that in the page editor and then, when the page is viewed, the content will be dynamically be fetched. This means you can update the referenced content and it will show the same changes on any page the content is included within.

Easily Grabbing the Syntax

Finding the id of a page can be difficult so a quick and easy way to find include tags is built into BookStack. View a page with some content you want to re-use. Use your mouse to select some content and you will see a popup appear. By default this contains a direct link to that content. If you click the link icon on the left it will switch to show you the include tag for that content. Simply copy that and place it in another page. Remove the # and content id to include the whole content of the page instead of just a single block.

Forcing Content IDs

When including a specific block of content the id of the block is used (part after the hash). By default these are generated by BookStack when you save a page. If you are using the WYSIWYG editor the id will stay the same unless the block is removed or re-formatted. In the markdown editor it changes with every save based on the content so while it may remain the same there's a good chance an ID can change therefore it's recommended to force an ID if you're using the content for includes.

Note: All ID values must start with "bkmrk" to avoid being overwritten.

WYSIWYG Editor

In the WYSIWYG editor you can force an ID by going into the source code view and adding it manually:

[图片：Forcing WYSIWYG Ids]

Markdown Editor

In the markdown editor you can simply insert HTML with an ID to ensure it does not change:

# Old Content
Copyright BookStack Enterprises 2020

# Revised with ID
<p id="bkmrk-include-copyright-text">Copyright BookStack Enterprises 2020</p>

Locating Include Tag Target

In some cases, you may come across an include tag and want to locate the page that the tag is targeting to include content from. You can do this by making use of BookStack page direct links, which follow the format <base_url>/link/<page_id>. Take the numeric ID (Located after the @ but before the # if existing) from the include tag then use it as the <page_id> in that described URL format and you'll be taken to the source page.

As an example if you had the include tag , you'd go to the URL path /link/5. A full example URL, using our demo instance, would be: https://demo.bookstackapp.com/link/5

Technical Include Logic

BookStack attempts to be smart with includes, to properly handle different content types and to be somewhat compliant with HTML rules. Below are some of the decisions BookStack will make when parsing includes:

Roles and Permissions

来源：BookStack 官方文档（开源）。原图外链已省略。

Within BookStack the abilities of a user are controlled by the roles assigned to them and the permissions provided to those roles. A user can be assigned multiple roles, in which case the permissions will stack and the user will receive any ability if any of the roles is provided that specific ability.

Managing Roles

Roles can be created and edited by an admin user by navigating to "Settings > Roles" within the BookStack interface. A set of default roles are provided in a fresh BookStack instance for common use cases. When altering a role you'll be able to change the system permissions which provides certain system-wide abilities. In addition, you'll see a range of "Asset Permissions" which are the default abilities provided to members of that role for content within the system. These may be overridden by content-level permissions. Many of the asset permissions have an "Own" option. This provides the members of that role the ability only when they are the owner of an item in the system.

Assigning Roles

Roles can be assigned to a user, by an admin, via editing a user's profile in the "Settings > Users" area of the BookStack interface. Here multiple roles can be assigned to a user, in which case the permissions will stack and the user will receive any ability if any of the roles is provided that specific ability.

Keep in mind that certain mechanisms within BookStack do have the ability to alter the roles of a user. These include:

Content Level Permissions

Permissions can be overridden at a Shelf, Book, Chapter or Page level where required. This can be done using the "Permissions" action when viewing such content, by any user that has a role permission to "Manage all/own permissions".

[图片：A view of the page permissions screen showing custom permissions being selected]

Within the permissions view you can use the "Override permissions for role" dropdown to select a role to set permissions for. When saved, these custom permissions will override the default permissions provided by roles for the configured content item.

An "Everyone Else" option is available to allow permission override/control for any roles that are not specifically overridden. By default, "Inherit defaults" will be selected for this item, which means that normal role permissions are used unless overridden. Deselecting this checkbox will use the permissions configured, in the same row, instead.

Content level permissions within BookStack have the following behavior:

When custom content level permissions are active and affecting the currently viewed item, you'll see an indicator within the details sidebar section. If you have permission to edit the active content level permissions, this acts as a link that will take you to the relevant permissions view, even if applied to a parent chapter or book.

[图片：Content level permissions indicator for a page showing "Book Permissions Active"]

Advanced Permission Logic

With all the different permission options in BookStack, the scenarios and logic can become quite complex as these combine & stack. To help make sense of permission control interplay, below are some general high-level rules that BookStack follows. Within the below, "content permissions" refers to those set directly on shelves, books, chapters, and pages.

There are three main levels of permission, which have different levels of specificity.
From least specific to most specific:

  1. Role permissions (Edited via the "Roles" interface).
  2. Content "Everyone Else" permissions (Edited via the "Permissions" view for an item).
  3. Role-specific content permissions (Also edited via the "Permissions" view for an item).

With those levels in mind:

Searching Content

来源：BookStack 官方文档（开源）。原图外链已省略。

The ability to search your documentation is vital to day-to-day use. There are a few locations within BookStack where you can search for your content. Below is a list of search functions within BookStack:

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:

Search Type Syntax Examples Description
Normal Searches <term_a> <term_b> london meeting Normal word searches across the name and description or body of your content. When mulitple terms are searched only one term has to match your content but content containing both terms will be higher in the results.
Exact Searches "<term>" "london meeting" Exact matches will require that the whole string within quotes exists in your content in exactly the same format. Use this if you're looking for an exact phrase containing or if you need to search for a term with spaces in.
Tag Searches [<name>]
[<operator><value>]
[<name><operator><value>] 		[location]
[=london]
[location=london]
[attendees>5] 		Tag searches allow you to find pages which have specific tags applied. You can search by tag name, by tag value or by both name and value. When searching by tag value an operator must be used to define the match type. You can use =, !=, <, >,<=, >= or like as operators. When using the like operator you can use % symbols to represent wildcards in your search.
Filter Searches {<filter_name>}
{<filter_name>:<filter_value>} 		See below Filters perform additional advanced functionality to make your searches even more powerfull. Some filters take values but some don't need to. See below for a full list of filters available.

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.

Syntax Examples Description
Date Filters
{updated_after:<date>} {updated_after:2016-12-30} Adds the condition that the content must have been last updated after the given date.
The date should be in the format YYYY-MM-DD
{updated_before:<date>} {updated_before:2016-12-30} Adds the condition that the content must have been last updated before the given date.
The date should be in the format YYYY-MM-DD
{created_after:<date>} {created_after:2016-12-30} Adds the condition that the content must have been created after the given date.
The date should be in the format YYYY-MM-DD
{created_before:<date>} {created_before:2016-12-30} Adds the condition that the content must have been created before the given date.
The date should be in the format YYYY-MM-DD
User Filters
{updated_by:<user_slug|me>} {updated_by:barry}
{updated_by:me}
Adds the condition that the content must have been last updated by the user of the given slug. If 'me' is used in place of a slug then it will find content that was last updated by the current logged-in user.
{created_by:<user_slug|me>} {created_by:barry}
{created_by:me}
Adds the condition that the content must have been created by the user of the given slug. If 'me' is used in place of a slug then it will find content that was created by the current logged-in user.
{owned_by:<user_slug|me>} {owned_by:barry}
{owned_by:me}
Adds the condition that the content must have be actively owned by the user of the given slug. If 'me' is used in place of a slug then it will find content that is owned by the current logged-in user.
Content Filters
{in_name:<search>} {in_name:London Meetings}
{in_name:Meetings} 		Will require the content to have the given <search> term in the name rather than the name or content body.
{in_body:<search>} {in_body:London Meetings}
{in_body:Meetings} 		Will require the content to have the given <search> term in the body rather than both the name or content body.
Option Filters
{is_restricted} {is_restricted} Will require the content to have content-level permissions active. Does not return items with only inherited asset permissions.
{viewed_by_me} {viewed_by_me} Will require the content to have been viewed by the current user at least once.
{not_viewed_by_me} {not_viewed_by_me} Will not return any content that has been viewed by the current user.
{type:<content_types>} {type:page|chapter|book}
{type:page|chapter}
{type:book}
Restricts the types of content that will be in the search results.
Use of this will depend on the type of search. For example, in a chapter search only pages are shown so this has no effect.

Search Examples

Below are some examples of using the above syntax and filters with descriptions:


Content Tags

来源：BookStack 官方文档（开源）。原图外链已省略。

While BookStack has a hierarchy at the center of the platform to organise content, you can sometimes desire an extra dimension of categorisation for content. Tags in BookStack offer this in a flexible manner, where a tag can represent a category and value across all levels & parts of the hierarchy.

Tag Format

Tags in BookStack have a name, but can also optionally have a value. This allows detailed & categorised levels of tagging where required for a mixed range of use-cases.

[图片：Three tags applied to content. A "Reviewed At" tag with value "20240611". A "Admin Books" tag with no value. A "Category" tag with value "Team planning"]

For example, you could use a tag named Critical with no value to mark important high priority pages. Alternatively, if you have a range of priorities, you could use a tag named Priority with a value of Critical. Using both a name and value here allows you to identify any content with a Priority set, in addition to allowing identification of just Critical content.

This can also come in useful when you want to use tags for metadata. For example, you may want to record content review dates, which you could achieve through a Reviewed At tag with value representing the last review date.

Adding & Managing Tags

Tags can be added to any level of the content hierarchy (Shelves, books, chapters & pages). You can apply tags when editing any such item. For shelves, books & chapters, tags are found in a dropdown section on the edit view:

[图片：View of editing tags for a Book, showing two tags, each as small cards with two edit zones within for tag name and value]

For pages, you can find tags in the sidebar toolbox when in the page editor:

[图片：View of the page editor, with a "Page Tags" section open in the sidebar]

When editing a tag name or value BookStack will show a list of potential existing relevant options to help you quickly fill the input. Suggestions for values will be just those used before for the chosen tag name, rather than all values across all tags.

While editing, you're also able to re-order & remove tags as desired. Any changes to tags are saved alongside when you save the item they're applied to.

Tag Display & Overview

When applied, tags are shown in a few areas of BookStack alongside the content they're applied to:

When viewing an item with tags applied, you can click the tag to start a tag search. Clicking the tag name will start a search for all content that also has a tag of that name. Clicking the value will start a search for other content that has that same tag name & value applied.

To view all tags being used, you can access an Tag overview page via the "View Tags" action found on the books or shelves index, or you can navigate straight to the /tags URL path. Here you'll see a list of all tag names used across content you have visibility of, alongside figures detailing their usage counts across each type of content.

[图片：View of a tags list, including a search box and sort options. It shows 4 tags as rows, and each row has a breakdown of usage.]

You can click the tag name, or item counts, to start a relevant filtered search. Where tag values are used, you can also click the link on the right to access a list of all tag values for that tag name, with a similar breakdown as before.

Tags in the Search Index

When content is indexed for searching in BookStack, tags names & values are considered as part of the search engine, and are even given a boost above normal content. This means you can boost content in search results for specific search terms using tags where needed.

Tag Search Operations

Content can be queried in BookStack by tag name or value. This can be used in many areas of BookStack where searching is made available. As mentioned in the sections above, you can often initiate tag searches via clicking tags or statistics in the tag index. Otherwise you can directly use the following syntax:

The following are valid operators: =, !=, <, >, <=, >=, like. When using the like operator you can use % symbols in the search value to represent wildcards.

Using this syntax you can get quite inventive. As an example, if you were applying Reviewed At tags with values in a format like 20240627 (YYYYMMDD) you could search for all content with "Reviewed At" dates before 2024 using:
[Reviewed At<20240101].

See our documentation on searching for more advanced search syntax.

Tags for Customization

Tags can also be handy for customization in a range of ways, even if just to assist as extra metadata or identification points. For example, you could use the logical theme system to run a custom action on page creations, and within that change behaviour or action based upon whether the parent Book has a specific tag.

Additionally, BookStack will convert tags to classes within the HTML templates used when viewing content in BookStack, which can then be used for easy tag-controlled customization & styling. Details of these tag classes can be found in our Hacking BookStack documentation here.

Default Page Editor

来源：BookStack 官方文档（开源）。原图外链已省略。

The default editor in BookStack is a 'What You See Is What You Get' (WYSIWYG) editor. The usage of this editor is similar to typical word-processing applications such as Word or Google Docs. For those that would prefer it, there is an alternative Markdown Editor which can be set as default or switched to where permissions allow.

Editor Shortcuts

The following shortcuts are available in the WYSIWYG Editor:

Shortcut (Windows & Linux/Mac) Description
Ctrl+S / Cmd+S Save Draft
Ctrl+Enter / Cmd+Enter Save Page & Continue
Ctrl+B / Cmd+B Bold
Ctrl+I / Cmd+I Italic
Ctrl+U / Cmd+U Underline
Ctrl+1 / Cmd+1
Ctrl+2 / Cmd+2
Ctrl+3 / Cmd+3
Ctrl+4 / Cmd+4 		Header Large
Header Medium
Header Small
Header Tiny
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