A simple Python script to sync markdown files from a docs/ folder to BookStack using the REST API.
- Auto-create/Update: Creates new chapters & pages, or updates existing ones (matched by name)
- Flatten nested folders:
technical-support/tenant1/→ Chapter "Technical Support - Tenant1" - Internal link conversion:
[Text](file.md)→[Text](/slug)(BookStack format) - Dry-run mode: Preview changes without execution
- Verbose logging: Debug mode for troubleshooting
- Smart matching: Finds existing content by name, updates instead of duplicating
- Python 3.8+
- requests >= 2.31.0
- markdown2 >= 2.4.12
- python-dotenv >= 1.0.0
pip install -r requirements.txtCreate a .env file (copy from .env.example):
cp .env.example .envEdit .env:
BOOKSTACK_BASE_URL=https://wiki.yourwebsite.com
BOOKSTACK_TOKEN_ID=your_token_id_here
BOOKSTACK_TOKEN_SECRET=your_token_secret_here
BOOKSTACK_BOOK_ID=3# Basic sync (create + update)
python bookstack_sync.py /path/to/docs
# Dry run (preview changes)
python bookstack_sync.py /path/to/docs --dry-run
# Create only (skip existing)
python bookstack_sync.py /path/to/docs --mode=create
# Update only (skip new)
python bookstack_sync.py /path/to/docs --mode=update
# Verbose (debug mode)
python bookstack_sync.py /path/to/docs --verbose
# Different book ID
python bookstack_sync.py /path/to/docs --book-id=5docs/
├── 01-introduction.md → Page "Introduction"
├── 02-structure.md → Page "Structure"
├── admin/ → Chapter "Admin"
│ ├── 01-page-example.md → Page "Page Example"
│ └── 02-finance.md → Page "Finance"
└── technical-support/ → Chapter "Technical Support"
├── 01-page-1.md → Page "Page 1"
└── tenant1/ → Chapter "Technical Support - Tenant1"
└── 01-page-helper.md → Page "Page Helper"
The script automatically converts markdown links to BookStack format:
# Before (local)
[Company Structure](02-structure.md)
[Page Helper](../technical-support/tenant1/01-page-helper.md)
# After (BookStack)
[Company Structure](/structure)
[Page Helper](/page-helper)- Update Mode: If content exists (matched by name), UPDATE it instead of creating duplicate
- Preserves page/chapter ID, URL, and history
- Only updates: name, html/markdown content, priority
- Never Delete: Skips deleted files, preserves all existing BookStack content
BookStack Docs Sync
===================
Docs path: /var/www/yourwebsite/docs
Target: https://wiki.yourwebsite.com/books/3-documentation
Scanning docs folder...
Found 3 markdown files in 2 folders
Fetching existing content from BookStack...
- 2 chapters found
- 5 pages found
Sync plan:
-----------
CREATE Chapter: Flow Chart
CREATE Page: Page 1
CREATE Chapter: Flow Chart - Akademik
CREATE Page: Page 2
Summary:
--------
- 2 chapters to CREATE
- 3 pages to CREATE
- 0 chapters to UPDATE
- 0 pages to UPDATE
- 0 items to DELETE
MIT