[PR #84] [CLOSED] feat(bookstack): add configurable export options #104

New issue

Closed

opened 2026-10-18 21:14:23 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-18 21:14:23 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/open-webui/oikb/pull/84
Author: @hexsm
Created: 7/16/2026
Status: ❌ Closed

Base: main ← Head: feature/bookstack-export-options

📝 Commits (5)

1bcec63 feat(bookstack): add configurable export options
357734e feat(bookstack): add chapter export output
0d19436 docs(bookstack): clarify export examples
eb56126 feat(bookstack): use scope path and id filters
a706834 docs: update changelog for BookStack exports

📊 Changes

5 files changed (+884 additions, -23 deletions)

View changed files

📝 CHANGELOG.md (+6 -0)
📝 docs/guide.md (+37 -0)
📝 src/oikb/cli.py (+10 -2)
📝 src/oikb/connectors/bookstack.py (+304 -21)
➕ tests/test_bookstack.py (+527 -0)

📄 Description

Summary

Adds configurable BookStack export options for selecting the source scope, included or excluded IDs, output type, file format, and path structure. The source path now selects the BookStack scope, while query parameters handle filtering and export options, leaving room for future filters such as tags.

This supersedes #80 and #82 and includes the combined BookStack export changes in one PR.

Addresses #75.

What Changed

Adds BookStack source scopes via the source path:
- bookstack:pages
- bookstack:books
- bookstack:shelves
- bookstack: defaults to bookstack:books
Adds BookStack source options:
include_ids=12,34
exclude_ids=12,34
output=pages|chapters|books
format=txt|md|html|pdf
structure=flat|hierarchical
Uses BookStack native export endpoints for pages, chapters, and books.
Supports syncing:
- individual pages
- pages from books
- chapter exports from books, while keeping pages outside chapters as individual page exports
- whole book exports
- pages, chapters, or books from shelves
Adds hierarchical paths for shelf/book/chapter structure where available.
Updates BookStack checksums so whole-book and chapter exports change when nested page content changes.
Adds BookStack parser and connector tests.
Documents the new BookStack options in the guide.

Examples

# Sync all pages from all BookStack books as Markdown files.
oikb sync bookstack: --kb-id your-kb-id

# Sync one specific BookStack page.
oikb sync 'bookstack:pages?include_ids=12' --kb-id your-kb-id

# Sync one BookStack book as chapter files; pages outside chapters remain page files.
oikb sync 'bookstack:books?include_ids=12&output=chapters' --kb-id your-kb-id

# Sync one whole BookStack book as a PDF file.
oikb sync 'bookstack:books?include_ids=12&output=books&format=pdf' --kb-id your-kb-id

# Sync all pages from one shelf and preserve shelf/book/chapter paths.
oikb sync 'bookstack:shelves?include_ids=5&structure=hierarchical' --kb-id your-kb-id

Validation

pytest: 40 passed
compileall -f src/oikb tests: passed
git diff --check: passed
Live BookStack diff checks:
- page scope
- default book pages
- chapter exports from book contents
- whole-book markdown/html/pdf exports
- plaintext exports
- hierarchical shelf pages
- hierarchical shelf book exports
Live upload/idempotency checks:
- single page sync, then unchanged repeat
- whole-book sync, then unchanged repeat
- chapter export sync, then unchanged repeat
- hierarchical shelf sync, then unchanged repeat

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/oikb/pull/84 **Author:** [@hexsm](https://github.com/hexsm) **Created:** 7/16/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feature/bookstack-export-options` --- ### 📝 Commits (5) - [`1bcec63`](https://github.com/open-webui/oikb/commit/1bcec6309960d784c458923d8ebac92206f43009) feat(bookstack): add configurable export options - [`357734e`](https://github.com/open-webui/oikb/commit/357734e91a093c9888dfad1111f814410ebbc12f) feat(bookstack): add chapter export output - [`0d19436`](https://github.com/open-webui/oikb/commit/0d194367439389c0fb583143ff60ad6fdbf67ebb) docs(bookstack): clarify export examples - [`eb56126`](https://github.com/open-webui/oikb/commit/eb56126acc6f94e1b45458f3702201093730023c) feat(bookstack): use scope path and id filters - [`a706834`](https://github.com/open-webui/oikb/commit/a7068341d3a7ed90d8db9b36386a495d74622330) docs: update changelog for BookStack exports ### 📊 Changes **5 files changed** (+884 additions, -23 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+6 -0) 📝 `docs/guide.md` (+37 -0) 📝 `src/oikb/cli.py` (+10 -2) 📝 `src/oikb/connectors/bookstack.py` (+304 -21) ➕ `tests/test_bookstack.py` (+527 -0) </details> ### 📄 Description ## Summary Adds configurable BookStack export options for selecting the source scope, included or excluded IDs, output type, file format, and path structure. The source path now selects the BookStack scope, while query parameters handle filtering and export options, leaving room for future filters such as tags. This supersedes #80 and #82 and includes the combined BookStack export changes in one PR. Addresses #75. ## What Changed - Adds BookStack source scopes via the source path: - `bookstack:pages` - `bookstack:books` - `bookstack:shelves` - `bookstack:` defaults to `bookstack:books` - Adds BookStack source options: - `include_ids=12,34` - `exclude_ids=12,34` - `output=pages|chapters|books` - `format=txt|md|html|pdf` - `structure=flat|hierarchical` - Uses BookStack native export endpoints for pages, chapters, and books. - Supports syncing: - individual pages - pages from books - chapter exports from books, while keeping pages outside chapters as individual page exports - whole book exports - pages, chapters, or books from shelves - Adds hierarchical paths for shelf/book/chapter structure where available. - Updates BookStack checksums so whole-book and chapter exports change when nested page content changes. - Adds BookStack parser and connector tests. - Documents the new BookStack options in the guide. ## Examples ```bash # Sync all pages from all BookStack books as Markdown files. oikb sync bookstack: --kb-id your-kb-id # Sync one specific BookStack page. oikb sync 'bookstack:pages?include_ids=12' --kb-id your-kb-id # Sync one BookStack book as chapter files; pages outside chapters remain page files. oikb sync 'bookstack:books?include_ids=12&output=chapters' --kb-id your-kb-id # Sync one whole BookStack book as a PDF file. oikb sync 'bookstack:books?include_ids=12&output=books&format=pdf' --kb-id your-kb-id # Sync all pages from one shelf and preserve shelf/book/chapter paths. oikb sync 'bookstack:shelves?include_ids=5&structure=hierarchical' --kb-id your-kb-id ``` ## Validation - pytest: 40 passed - compileall -f src/oikb tests: passed - git diff --check: passed - Live BookStack diff checks: - page scope - default book pages - chapter exports from book contents - whole-book markdown/html/pdf exports - plaintext exports - hierarchical shelf pages - hierarchical shelf book exports - Live upload/idempotency checks: - single page sync, then unchanged repeat - whole-book sync, then unchanged repeat - chapter export sync, then unchanged repeat - hierarchical shelf sync, then unchanged repeat --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-18 21:14:23 +00:00