bookstack/website
Fork 4
Code Issues 5 Pull requests Activity

Merge branch 'v0.16'

Browse source
This commit is contained in:
Dan Brown 2017-04-23 20:40:32 +01:00
commit 302f5c3f2e
Signed by: danb
GPG key ID: 46D9F943C24A2EF9
8 changed files with 335 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

110
content/blog/beta-release-v0-16-0.md Normal file
View file

@ -0,0 +1,110 @@
+++
categories = ["Releases"]
tags = ["Releases"]
title = "Beta Release v0.16.0"
date = 2017-04-23T21:00:00Z
author = "Dan Brown"
image = "/images/blog-cover-images/old-books-jan-mellstrom.jpg"
description = "BookStack v0.16 released with revamped search, spellcheck and more"
slug = "beta-release-v0-16-0"
draft = false
+++
Another BookStack release is upon us. Since the last release work has been put into
spring-cleaning the search system which is detailed below. Community contributions
have gained some momentum bringing in some fantastic new features and fixes.
* [Update instructions](https://www.bookstackapp.com/docs/admin/updates)
* [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v0.16.0)
### New Search System
The old search system had some issues. It was based on MySQL fulltext indexes which
allowed the search to be efficient but smaller search terms would be ignored or
non-english characters would not be matched. It also meant that BookStack relied on MySQL.
The search system has been re-written with a custom, more basic, solution that
should provide a better experience for most users. The search index is now built
on a standard database table and all text content on a page is indexed. Search terms
are checked against this index in a prefix-match like manner. This means that
the search term only needs to match the start of an indexed 'word'.
In addition to the back-end system being re-written the main search interface
has had an update:
![New Search System](/images/2017/04/new-search-interface.png)
The result list is now simpler, With chapters, books and pages all in the same
list, ranked by how much they match the given search terms. On the right hand side
options have been added to expose inputs to allow more advanced searches.
Exact match terms and tag searches, which were in previous releases, are now
easier to use since you can add them in this sidebar without having to remember
the exact search syntax.
New to the search system is a collection of advanced search filter options. These
allow you to refine your search better than ever with options such as finding
items 'Created by me' and a range of date filters.
Full details of the search system as well as a list of available filters can be
found on [this new documentation page](/docs/user/searching).
### Spellchecker
A spellchecker has been quite an important omission for a text-heavy based platform
such as BookStack but I'm pleased to say that spellchecking support is now enabled
on pages. Thanks to [@Abitjeet](https://github.com/BookStackApp/BookStack/issues/354) whom
enabled this feature within BookStack.
![Spellchecking support](/images/2017/04/spellchecking.png)
BookStack uses the native browser spell checking functionality to achieve this which ensures
the correct settings, such as language, will be correct and any custom-saved words
will be taken into account.
### Translation Updates
With this release comes another round of updates to the translations.
The Spanish translations have had an update to be much more complete
[thanks again to @diegoseso](https://github.com/BookStackApp/BookStack/pull/357)
and now Slovak translations are available [thanks to @jendrol](https://github.com/BookStackApp/BookStack/pull/358).
### Page Revision Counts
The number of updates is now recorded
and displayed at the bottom of the page. Along with this count, A revision number
can now been seen when viewing the list of revisions to a page. This enables you
to uniquely reference each revision individually which can be essential in strict
record keeping environments.
### Full List of Changes
* New search system with new search filter system.
* New UI for searching content.
* Fixes issues with search terms that are short or contain accents.
* Added spell checker support to WYSIYG page editor. (Thanks to [@Abitjeet](https://github.com/BookStackApp/BookStack/issues/354)).
* Page revision ID/Count system added.
* Slovak translations added. (Thanks to [@jendrol](https://github.com/BookStackApp/BookStack/pull/358)).
* Spanish translations updated. (Thanks to [@diegoseso](https://github.com/BookStackApp/BookStack/pull/357)).
* The page navigation highlighting will now fade out.
* Option to configure logging method added. (Thanks to [@solidnerd](https://github.com/BookStackApp/BookStack/pull/363)).
* Switched out markdown renderer library to [markdown-it](https://github.com/markdown-it/markdown-it):
* Fixes ability to have brackets in markdown urls.
* Allows backslash escaping in markdown tables.
* Updated permission system with ability to hide parent items and have the child be visible.
* Confirmation emails may now be queued (Thanks to [@DaneEveritt](https://github.com/BookStackApp/BookStack/pull/362)).
### Next Steps
I'm thinking that the next chunk of work for BookStack may be more refinement
and maintenance rather than big new features. A few areas, such as the test suite
and JavaScript framework, need an update to be aligned. With the change to the
search system we can also look at supporting other database types.
Notifications are becoming more requested, For which an initial discussion of
using webhooks [can be found here](https://github.com/BookStackApp/BookStack/issues/147)
although I have some concerns about keeping BookStack performant at scale when
notification come into play.
----
<span style="font-size: 0.8em;opacity:0.8;">Header Image Credits: <a href="https://unsplash.com/@mrjane" target="_blank">Jan Mellström</a></span>

200
content/docs/user/searching.md Normal file
View file

@ -0,0 +1,200 @@
+++
title = "Searching Content"
description = "Searching for specific content within BookStack and learning the advanced search syntax"
date = "2017-04-16"
type = "user-docs"
+++
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:
* **Header Search Bar** - The search bar/link in the header of every page allows you to search from anywhere. This search is a global search which will look across all books, chapters and pages in your system. This page contains an interface to help you build a more advanced search. This interface simply generates a more advanced search term using the syntax described below.
* **Book/Chapter Search Bar** - When viewing a book or chapter a search bar can be found in the top of the right sidebar. These searches will look across all child items.
* **Move & Link Selection** - When choosing to move a page/chapter or when selecting a page/chapter/book to link to within the editor the most popular items are shown but you also have the ability to search.
---
## 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:
<table width="100%">
<tr style="font-weight:bold;">
<td width="16%">Search Type</td>
<td width="20%">Syntax</td>
<td width="16%">Examples</td>
<td>Description</td>
</tr>
<tr>
<td>Normal Searches</td>
<td>&lt;term_a&gt; &lt;term_b&gt;</td>
<td>london meeting</td>
<td>Normal word search 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.</td>
</tr>
<tr>
<td>Exact Searches</td>
<td>"&lt;term&gt;"</td>
<td>"london meeting"</td>
<td>Exact matches will require that the whole string within quotes exists in your content in exactly the same format. Used this if you're looking for an exact phrase containing or if you need to search for a term with spaces in.</td>
</tr>
<tr>
<td>Tag Searches</td>
<td class="text-small">
[&lt;name&gt;] <br>
[&lt;operator&gt;&lt;value&gt;] <br>
[&lt;name&gt;&lt;operator&gt;&lt;value&gt;]
</td>
<td>
[location] <br>
[=london] <br>
[location=london] <br>
[attendees>5]
</td>
<td>Tag searches allow you to find pages with that 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 <code>=</code>, <code>!=</code>, <code>&lt;</code>, <code>&gt;</code>,<code>&lt;=</code>, <code>&gt;=</code> or <code>like</code> as operators. When using the <code>like</code> operator you can use <code>%</code> symbols to represent wildcards in your search.</td>
</tr>
<tr>
<td>Filter Searches</td>
<td class="text-small">
{&lt;filter_name&gt;} <br>
{&lt;filter_name&gt;:&lt;filter_value&gt;}
</td>
<td>See below</td>
<td>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.</td>
</tr>
</table>
---
## 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.
<table width="100%">
<tr style="font-weight:bold;">
<td width="25%">Syntax</td>
<td width="25%">Examples</td>
<td>Description</td>
</tr>
<tr style="font-weight:bold;">
<td colspan="3">Date Filters</td>
</tr>
<tr>
<td>{updated_after:&lt;date&gt;}</td>
<td>{updated_after:2016-12-30}</td>
<td>Adds the condition that the content must have been last updated after the given date. <br> The date should be in the format YYYY-MM-DD</td>
</tr>
<tr>
<td>{updated_before:&lt;date&gt;}</td>
<td>{updated_before:2016-12-30}</td>
<td>Adds the condition that the content must have been last updated before the given date. <br> The date should be in the format YYYY-MM-DD</td>
</tr>
<tr>
<td>{created_after:&lt;date&gt;}</td>
<td>{created_after:2016-12-30}</td>
<td>Adds the condition that the content must have been created after the given date. <br> The date should be in the format YYYY-MM-DD</td>
</tr>
<tr>
<td>{created_before:&lt;date&gt;}</td>
<td>{created_before:2016-12-30}</td>
<td>Adds the condition that the content must have been created before the given date. <br> The date should be in the format YYYY-MM-DD</td>
</tr>
<tr style="font-weight:bold;">
<td colspan="3">User Filters</td>
</tr>
<tr>
<td>{updated_by:&lt;user_id|me&gt;}</td>
<td>
{updated_by:10} <br>
{updated_by:me} <br>
</td>
<td>Adds the condition that the content must have been last updated by the user of the given numeric ID. If 'me' is used in place of a numeric ID then it will find content that was last updated by the current logged-in user.</td>
</tr>
<tr>
<td>{created_by:&lt;user_id|me&gt;}</td>
<td>
{created_by:10} <br>
{created_by:me} <br>
</td>
<td>Adds the condition that the content must have been created by the user of the given numeric ID. If 'me' is used in place of a numeric ID then it will find content that was created by the current logged-in user.</td>
</tr>
<tr style="font-weight:bold;">
<td colspan="3">Content Filters</td>
</tr>
<tr>
<td>{in_name:&lt;search&gt;}</td>
<td>
{in_name:London Meetings} <br>
{in_name:Meetings}
</td>
<td>Will require the content to have the given <code>&lt;search&gt;</code> term in the name rather than the name <strong>or</strong> content body.</td>
</tr>
<tr>
<td>{in_body:&lt;search&gt;}</td>
<td>
{in_body:London Meetings} <br>
{in_body:Meetings}
</td>
<td>Will require the content to have the given <code>&lt;search&gt;</code> term in the body rather than both the name <strong>or</strong> content body.</td>
</tr>
<tr style="font-weight:bold;">
<td colspan="3">Option Filters</td>
</tr>
<tr>
<td>{is_restricted}</td>
<td>
{is_restricted}
</td>
<td>Will require the content to have content-level permissions active. Does not return items with only inherited asset permissions.</td>
</tr>
<tr>
<td>{viewed_by_me}</td>
<td>
{viewed_by_me}
</td>
<td>Will require the content to have been viewed by the current user at least once.</td>
</tr>
<tr>
<td>{not_viewed_by_me}</td>
<td>
{not_viewed_by_me}
</td>
<td>Will not return any content that has been viewed by the current user.</td>
</tr>
<tr>
<td>{type:&lt;content_types&gt;}</td>
<td>
{type:page|chapter|book} <br>
{type:page|chapter} <br>
{type:book} <br>
</td>
<td>Restricts the types of content that will be in the search results. <br> 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.</td>
</tr>
</table>
---
## Search Examples
Below are some examples of using the above syntax and filters with descriptions:
* `"my cat" {viewed_by_me} {updated_after:2017-01-24}`
* `"my cat"` - Search for content containing the exact phrase 'my cat'
* `{viewed_by_me}` - that has been viewed by me
* `{updated_after:2017-01-24}` - and was last updated after the 24th of Jan 2017.
<br>
* `textbook discussion [meeting] {type:page} {created_by:me}`
* `textbook discussion` - Search content for the words `textbook` or `discussion`
* `[meeting]` - only show content that has a `meeting` tag applied
* `{type:page}` - only show pages, Hide chapters and books
* `{created_by:me}` - that was created by me.
<br>
* `{type:book|chapter} {created_by:me} {created_after:2016-08-12} {created_before:2017-02-18}`
* `{type:book|chapter}` - Search all books and chapters
* `{created_by:me}` - that were created by me
* `{created_after:2016-08-12} ` - after the 12th of Aug 2016
* `{created_before:2017-02-18}` - but before the 18th of Feb 2017