homeylab/bookstack-file-exporter repository overview

⁠bookstack-file-exporter

Table of Contents

• Background⁠
  • Features⁠
  • Use Case⁠
• Documentation⁠
• Potential Breaking Upgrades⁠
• Future Items⁠

⁠Background

If you encounter any issues, want to request an additional feature, or provide assistance, feel free to open a Github issue.

This self-admittedly, overly complicated tool provides a way to export Bookstack⁠ pages and their content (text, images, attachments, metadata, etc.) into a relational parent-child layout locally with an option to push to remote object storage locations. See Backup Behavior⁠ section for more details on how pages are organized. Image and attachment links can also be modified in markdown and html exports to point to local exported paths.

This small project was mainly created to run as a cron job in k8s but works anywhere. This tool allows me to export my docs in markdown, or other formats like pdf. I use Bookstack's markdown editor as default instead of WYSIWYG editor and this makes my notes portable anywhere even if offline.

⁠Features

What it does:

• Discover and build relationships between Bookstack Shelves/Books/Chapters/Pages to create a relational parent-child layout
• Export Bookstack pages and their content to a .tgz archive
• Additional page content: images, attachments, and metadata can also be exported
• The exporter can also Modify Links⁠ to replace image and/or attachment links with local exported paths for a more portable backup
• Fine grained filtering, selectable export levels (books/chapters/pages), and parallelization to speed up download of contents and assets
• YAML configuration file for repeatable and easy runs
• Can be run via Python⁠ or Docker⁠
• Can push archives to remote object storage like MinIO⁠ or AWS S3⁠
• Basic housekeeping option (keep_last) to keep a tidy archive destination
• Can run in application mode (always running) using run_interval (interval-based) or run_schedule (cron-based) properties. Used for scheduling backups.

Supported backup targets are:

1. local filesystem
2. S3-compatible object storage — AWS S3, MinIO, Ceph, Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, etc. There is no type field; a target is treated as a custom store or AWS S3 based on whether an endpoint is set. See Remote Storage⁠.

Supported backup formats are based on Bookstack API and shown here⁠ and below:

1. html
2. pdf
3. markdown
4. plaintext
5. zip

⁠Use Case

The main use case is to backup all docs in a relational directory-tree format to cover the scenarios:

1. Share docs with another person to keep locally.
2. Offline copy wanted.
3. Back up at a file level as an accessory or alternative to disk and volume backups.
4. Migrate all Bookstack page contents to Markdown documenting for simplicity.
5. Provide an easy way to do automated file backups locally, in docker, or kubernetes⁠ for Bookstack page contents.

⁠Documentation

Detailed docs live under docs/⁠:

• Getting Started⁠ — install via Pip/Docker/Helm, CLI options, environment variables, authentication
• Configuration⁠ — full config.yml reference, all options, environment variables, export level, parallel export
• Operations⁠ — run modes, scheduling, run outcomes & exit codes, graceful shutdown, health endpoint
• Filters⁠ — include/exclude shelves, books, chapters, pages by name
• Backup Behavior⁠ — archive layout, file naming, images (incl. secure image storage), attachments, modify-links
• Remote Storage⁠ — MinIO / S3 upload, credential resolution, multi-target behavior, v2→v3 migration
• Notifications⁠ — apprise notifications on export success/failure

⁠Potential Breaking Upgrades

Below are versions that have major changes to the way configuration or exporter runs.

⁠Future Items

1. Be able to pull images locally and place in their respective page folders for a more complete file level backup.
2. Include the exporter in a maintained helm chart as an optional deployment. The helm chart is here⁠.
3. Be able to modify markdown links of images to local exported images in their respective page folders for a more complete file level backup.
4. Be able to pull attachments locally and place in their respective page folders for a more complete file level backup.
5. Export S3 and more options.
6. Filter shelves and books by name - for more targeted backups. Example: you only want to share a book about one topic with an external friend/user.
7. Be able to pull media/photos from 3rd party providers like drawio