BookStack Code Mirror - website/blob - readme.md

   1 # BookStack Site, Documentation & Blog
   2
   3 This project holds all the data for the https://www.bookstackapp.com/ website.
   4
   5 This site is built using [Hugo](https://gohugo.io). Images are stored using `git-lfs`.
   6 The "extended" version of hugo must be used (Has support for certain features like WebP resize).
   7
   8 ### Data Locations
   9
  10 * Blog Posts - `content/posts`
  11 * Docs - `content/docs`
  12 * Theme - `themes/bookstack`
  13
  14 ### Hacks
  15
  16 The website also contains a repository of customization hacks which can be found at [the /hacks](https://www.bookstackapp.com/hacks/) part of the site.
  17 These are managed via a [separate "Hacks" repo](https://codeberg.org/bookstack/hacks) which is part of this repository as a git submodule.
  18 This is included into this site repo as [a module mount](https://gohugo.io/configuration/module/#mounts).
  19
  20 ### Theme
  21
  22 The theme is custom made with snippets taken from the [hugo capser theme](https://github.com/vjeantet/hugo-theme-casper).
  23
  24 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.
  25
  26 ### Search
  27
  28 Search is performed using [webidx](https://github.com/gbxyz/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](https://github.com/sql-js/sql.js).
  29
  30 This files required are all in this repo, and hacked to suit our use-case.
  31 The script to build the index is located at `search/webidx.pl`, and can be ran via the npm script
  32
  33 ```bash
  34 npm run build:search
  35 ```
  36
  37 **Note:** you may need to install some dependencies to run the script see the `search/webidx.pl` for more information.
  38
  39 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:
  40
  41 ```nginx
  42 location ~* \.(db)$ {
  43   brotli_static on;
  44   gzip_static on;
  45 }
  46 ```
  47
  48 Much of the search UI handling logic can be found in our `themes/bookstack/static/js/scripts.js` file.