From: Dan Brown Date: Wed, 6 Mar 2024 13:03:51 +0000 (+0000) Subject: Added new content storage docs page X-Git-Url: http://source.bookstackapp.com/website/commitdiff_plain/aa5e2de6dd4e9f86b56fea8a0f5e249325b364bd Added new content storage docs page Closes #180 --- diff --git a/content/docs/admin/backup-restore.md b/content/docs/admin/backup-restore.md index c287d91..81ddd3a 100644 --- a/content/docs/admin/backup-restore.md +++ b/content/docs/admin/backup-restore.md @@ -7,8 +7,7 @@ type = "admin-doc" While BookStack does not currently have a built-in way to backup and restore content, it can usually be done via the command line with relative ease. - -Please note the below commands are based on using Ubuntu. If you are using a +The below commands are based on using Ubuntu. If you are using a different operating system you may have to alter these commands to suit. --- diff --git a/content/docs/admin/content-storage.md b/content/docs/admin/content-storage.md new file mode 100644 index 0000000..6db727a --- /dev/null +++ b/content/docs/admin/content-storage.md @@ -0,0 +1,122 @@ ++++ +title = "Content Storage Format" +date = "2024-03-03" +type = "admin-doc" ++++ + +When building up a documentation store, or assessing platform options, it can be useful to understand how data is stored +so you know how portable & accessible your content is. +This page aims to clearly lay-out how content is stored within BookStack and what our general project aims +are when it comes to data storage, content formats, and how these may lead design & development decisions. + +{{}} + +--- + +### Our Goals & Ideals + +When it comes to core content provided into BookStack we want to avoid "locking" users into our platform. +We believe data should be portable and to common standard formats, so that's what we aim for. +For core page content we aim to stick to relatively simple HTML, with an aim to Commonmark for markdown +where used (see ["page content" section](#page-content) below for more details on this). + +While we don't officially support export to (or import from) other specific platforms as part +of the core project, we aim to provide options & guidance so this can be achieved +where desired. + +When assessing features & changes to BookStack, keeping content to simple standards in the interest +of portability takes a very high level of priority in decisions. +We have pushed back against many editor & content-format feature requests, in the interest of +not complicating the content structure. + +--- + +### Storage Formats + +BookStack is primarily a database-driven system. The vast majority of data and metadata can be found +in tables of the attached database. For anything not specifically mentioned below, it's likely in the database. +If your aim is BookStack instance backup/restore of any kind, then +you should focus on performing a database dump (in addition to backing up files) as per our +[backup/restore guidance here](/docs/admin/backup-restore/). + +#### Page Content + +Page content is primarily stored as HTML, with the `html` column of the `pages` database table. +We aim (as per our goals) to keep the range of HTML formats limited to common basic HTML with little +depth/structure complexity where possible. There's a few custom classes used (for alignment & callout blocks) +but we now try to avoid the addition & use of new custom classes. Some formatting options +may use inline HTML styles (Text color for example). + +For pages written in Markdown, the original input markdown will be stored within the `markdown` column +of the `pages` table. Within BookStack's official functions, we generally focus on standardising +markdown support to [commonmark](https://commonmark.org/), with the extra additions of markdown tables, task-lists, and HTML. + +Page content may reference other items within BookStack, and other external resources. +In official functions, we aim to standardise on always using full absolute URLs, rather than any relative +or custom dynamic references. This ensures such links/references work regardless of usage context, and +having a full absolute URL provides a base URL/host that can be easily searched upon & detected +where required. + +There is one custom dynamic feature when it comes to page content, that being is our +[dynamic include tag](/docs/user/reusing-page-content/) system, which provides on-load +inclusion of other content onto a page. Includes are not stored ready-parsed, they are +handled at page display time since permissions can affect the result. +Other than this, we avoid adding extra dynamic/"smart"/"magic" features to core page content. + +#### Images & Drawings + +Images are stored as standard image files, typically on the local filesystem but that +can depend on [configured storage method](/docs/admin/upload-config/). +When uploading, image file names may be altered/generated by BookStack. +Upon upload BookStack will store the originally provided image file data but also +create & store resized images for convenience, mainly for reduced file size for more efficient +loading & display. These system resized images are stored within directories that have names staring with +`scaled-` or `thumbs-`, with these directories being in the same location as the original image files. + +Drawings are treated much the same as images. +When a drawing is saved in the integrated [diagrams.net](https://diagrams.net) (Previously draw.io) +editor, they're exported and saved within BookStack as standard PNG images. +These PNG image files are embedded with the original drawing data, so they can be reloaded back into +the diagrams.net to be fully editable again. You can drag/import these PNG files into any +diagrams.net/draw.io instance for full re-editing capabilities. + +#### Attachments + +Attachments are stored as files, typically on the local filesystem but that +can depend on [configured storage method](/docs/admin/upload-config/). +Filenames, including the file extension, will be altered so it may be hard to identify +attachments on the filesystem by name. If you need to do this, you can +use the `attachments` table of the database as a reference. The `path` column +represents attachment file locations, relative to top-level storage location. + +--- + +### Egress Options + +*Note: This is not relevant for BookStack-only backup/restore operations, see [our guidance here](/docs/admin/backup-restore/) for that.* + +To get data out of BookStack (in bulk) there's two main ways: + +- [The BookStack REST API](/docs/admin/hacking-bookstack/#bookstack-api) +- Fetch/export directly from the database. + +The REST API presents a nice scriptable, primarily JSON-based, interface. Various example scripts +can be found in [our api-scripts repo](https://github.com/BookStackApp/api-scripts). +The API covers all core content types, including their RAW underlying data. +The API does provided access to export formats, but most of these may perform some transformation +or be lossy in operation. The one exception may be the (contained) HTML export option since +this will attempt to embed image content into the page which could make the content +more portable, and potentially help avoid having to manage images separately. + +Otherwise, directly interfacing with, or exporting from, the database is always an option. +We attempt to have sensible table and column naming, with a simple overall database structure, +so navigating around to extract/format data as required shouldn't be too much trouble if confident +with database systems. + +For either of these, some potential pain points for egress (migration away) from BookStack could be: + +- Handling image/media/attachment content, and mapping/linking their use from content. +- Supporting any additional metadata you want to migrate. +- Handling any complex/custom elements of the content format. + +The specifics & overall complexity can ultimately depend on what you need to migrate/transfer to, in addition to the skills & tools you have available. \ No newline at end of file diff --git a/themes/bookstack/layouts/partials/menu_admin_docs.html b/themes/bookstack/layouts/partials/menu_admin_docs.html index dc55194..b33f149 100644 --- a/themes/bookstack/layouts/partials/menu_admin_docs.html +++ b/themes/bookstack/layouts/partials/menu_admin_docs.html @@ -3,8 +3,9 @@ @@ -16,6 +17,7 @@
  • Backup & Restore
  • Debugging
  • System CLI
    • +
  • Filesystem Permissions
    • diff --git a/themes/bookstack/sass/styles.scss b/themes/bookstack/sass/styles.scss index 89782e3..521d2be 100644 --- a/themes/bookstack/sass/styles.scss +++ b/themes/bookstack/sass/styles.scss @@ -275,7 +275,7 @@ input[type=text] { .docs-index-row { display: flex; flex-wrap: wrap; - column-gap: 6rem; + column-gap: 5rem; row-gap: .5rem; justify-content: left; }