BookStack Sync

Sync a folder in your Obsidian vault with a BookStack knowledge base.

• Pull every book, chapter and page from BookStack into Markdown notes.
• Two-way sync (optional, off by default): write local edits back to BookStack.
• Change detection per page, so re-syncing only touches what actually changed.
• Conflict handling when a page was edited on both sides.

This plugin was built for knowledgebase.stellwerk.cloud ↔ the Oper Notes folder, but the URL and folder are configurable.

How the vault mirrors BookStack

<Vault folder>/
  <Shelf name>/
    <Book name>/
      <Page name>.md
      <Chapter name>/
        <Page name>.md
  <Book name>/               # books on no shelf stay at the top level
    <Page name>.md

Grouping books into shelf folders is on by default (Group books by shelf). A book that sits on several shelves is filed under the first one alphabetically; a book on no shelf goes directly under the vault folder. Turn the setting off for a flat <Book name>/… layout.

Every synced note gets a small managed frontmatter block that links it back to BookStack:

---
bookstack:
  id: 123
  book_id: 4
  chapter_id: 0
  slug: my-page
  updated_at: "2026-09-01T10:00:00.000000Z"
  url: https://knowledgebase.stellwerk.cloud/books/handbook/page/my-page
---

Only the note body (everything after the frontmatter) is compared and pushed. You can add your own frontmatter keys and they will be preserved.

Setup

1. In BookStack, open Edit Profile → API Tokens → Create Token. Copy the Token ID and Token Secret (the secret is shown only once). The account needs the Access System API permission.
2. In Obsidian: Settings → Community plugins → BookStack Sync.
3. Enter the BookStack URL.
4. Provide the token. By default the plugin uses Obsidian's secret storage (secret IDs bookstack-token-id and bookstack-token-secret) — either fill the fields here, or set those secrets yourself and the plugin will pick them up. Turning the toggle off falls back to storing the token in this vault.
5. Press Test connection.
6. Set the Vault folder (default Knowledgebase).
7. Run the command BookStack Sync: Pull from BookStack (or click the ribbon icon).

Commands

Command	Action
Pull from BookStack	Download changes from BookStack into the vault.
Push to BookStack	Upload local changes (only when push is enabled).
Sync with BookStack (pull and push)	Pull, then push if enabled.

The ribbon icon runs a pull (or a full sync when push is enabled). Optional sync on startup and a sync interval are in the settings.

Two-way sync

Turn on Enable push (two-way sync) to write local changes back.

• Editing a linked note and running a push updates the BookStack page.
• A new .md file inside a book folder becomes a new page in that book (or chapter). Missing books/chapters are created when Create books and chapters in BookStack is on; a book created inside a shelf folder is also added to that shelf. Moving an existing book between shelf folders locally does not reassign its shelf (the next pull moves it back).
• Deleting a note deletes the BookStack page only when Push local deletions is on (off by default).

Conflicts

When a page changed both in BookStack and locally:

Strategy	Behaviour
Keep both (default)	Local note is kept; the BookStack version is saved next to it as <name> (BookStack conflict <date>).md.
BookStack wins	Local note is overwritten with the BookStack version.
Local wins	Local note is kept; on the next push it overwrites BookStack.

Limitations

• Attachments and images are not downloaded. Image links keep pointing at the BookStack server.
• BookStack pages written in the WYSIWYG editor are converted from HTML to Markdown on pull. Complex HTML may not round-trip perfectly. Pages written in BookStack's Markdown editor are stored verbatim. Pushing a note always sends Markdown, which switches that page to the Markdown editor in BookStack.
• With secret storage on (the default), the API token is kept in Obsidian's secret store, not in the vault. With it off, the token sits in .obsidian/plugins/bookstack-sync/data.json in plain text like other plugin settings — don't sync that file to an untrusted location.
• Requires Obsidian 1.11.4 or newer (for secret storage and trashFile).

Development

npm install
npm run dev     # watch build
npm run build   # type-check + production bundle
npm run lint

Copy main.js, manifest.json (and styles.css if present) into <Vault>/.obsidian/plugins/bookstack-sync/ and reload Obsidian.