BookStack Home Assistant Integration

Integrate your BookStack instance with Home Assistant to monitor content statistics and track updates.

If you just want to show your appreciation, you can sponsor the project or send a one off donation using the links below:

Features

The integration provides the following sensors in Home Assistant:

Note

The integration supports translation of all sensor names. Get in touch if you'd like to help translate the integration into your language!

Aggregate Sensors

• Shelves: Total number of shelves
• Books: Total number of books
• Chapters: Total number of chapters
• Pages: Total number of pages
• Users: Total number of registered users
• Images: Total number of images in the gallery
• Attachments: Total number of file attachments

Per-Shelf Sensors (when enabled)

For each shelf in your BookStack instance, the following sensors will be created:

• {Shelf Name} Books: Number of books on this shelf
• {Shelf Name} Chapters: Number of chapters across all books on this shelf
• {Shelf Name} Pages: Number of pages across all books on this shelf

Additional Sensors

• Last Updated Page: Timestamp of the most recently updated page, with additional attributes:
  • page_name: Name of the updated page
  • page_id: BookStack page ID of the page
  • updated_by: Name of the user who updated it
  • updated_by_id: BookStack user ID of the user who updated it
  • page_url: URL linking directly to the page
• Connectivity: Diagnostic sensor showing BookStack availability
• Update: Indicates if a newer version of BookStack is available

Note

Upgrading BookStack from Home Assistant is not possible and thus is not supported by the update entity.

Actions (formerly Services)

The integration provides the following Home Assistant actions:

• bookstack.create_book: Create a new Book in BookStack and assign it to a Shelf.
• bookstack.create_page: Create a new Page in a specific Book in BookStack.
• bookstack.append_page: Appends content and tags to an existing Page in BookStack.
• bookstack.list_books: Generates a list of all books in BookStack. Optionally filtered to a specific shelf ID.
• bookstack.list_chapters: Generates a list of all chapters in a specific BookStack book.
• bookstack.list_pages: Generates a list of all pages in a specific BookStack book. Optionally filtered to a specific chapter ID.

Note

The "list" actions can be useful for finding BookStack item IDs, as these can be difficult to locate within the BookStack UI.

Installation

HACS (Recommended)

Tip

The integration has been submitted for inclusion in the HACS default integrations list. Try searching HACS before following the below instructions in case it has already been accepted and can be installed without adding it as a custom repository.

1. Open HACS in Home Assistant
2. Click the 3 dots in the top right corner
3. Select "Custom repositories"
4. Add the URL: https://github.com/MattFryer/hass-bookstack
5. Select category: "Integration"
6. Click "Add"
7. Click "Download" on the BookStack integration
8. Restart Home Assistant

Manual Installation

1. Copy the custom_components/bookstack folder to your config/custom_components/ directory
2. Restart Home Assistant
3. Add the integration via Settings → Devices & Services → Add Integration → BookStack

Configuration

Initial Setup

1. Navigate to Settings → Devices & Services → Add Integration
2. Search for "BookStack"
3. Enter your BookStack details:
   • BookStack URL: The base URL of your BookStack instance (e.g., https://bookstack.example.com)
   • API Token ID: Found under your BookStack profile → API Tokens
   • API Token Secret: Found under your BookStack profile → API Tokens
   • Scan Interval: How often to check BookStack for updates (default: 300 seconds)
   • Enable per-shelf sensors: Creates individual sensors for each shelf (default: enabled)

Automation Examples

The following are example Home Assistant automations which you can use:

Notify when content is updated

Notify when someone updates a page in BookStack:

automation:
  - alias: "BookStack Page Updated"
    trigger:
      - platform: state
        entity_id: sensor.bookstack_last_updated_page
    action:
      - service: notify.mobile_app
        data:
          title: "BookStack Updated"
          message: >
            {{ trigger.to_state.attributes.page_name }} 
            was updated by {{ trigger.to_state.attributes.updated_by }}

Alert when BookStack goes offline

Send an alert when BookStack goes offline:

automation:
  - alias: "BookStack Offline Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.bookstack_connectivity
        to: "off"
        for:
          minutes: 5
    action:
      - service: notify.mobile_app
        data:
          title: "BookStack Offline"
          message: "BookStack server is unreachable"

Track content growth

Send a weekly report on Monday with stats about BookStack:

automation:
  - alias: "BookStack Weekly Report"
    trigger:
      - platform: time
        at: "09:00:00"
    condition:
      - condition: time
        weekday:
          - mon
    action:
      - service: notify.mobile_app
        data:
          title: "BookStack Weekly Stats"
          message: >
            Total Content:
            {{ states('sensor.bookstack_pages') }} pages
            {{ states('sensor.bookstack_books') }} books
            {{ states('sensor.bookstack_shelves') }} shelves

Action Examples

The following are examples of using the Home Assistant actions available with this integration:

Creating a book

Create a new book in BookStack and assigning it to a shelf:

action: bookstack.create_book
data:
  shelf_id: 5
  name: "My New Book"
  description: "Notes about my setup"
  tags:
    - "home-automation"
    - "networking"
response_variable: new_book

After the action runs, the response_variable will contain all information about the book which the BookStack API returns. The information in the response can be used in following actions. Most useful are:

• new_book.id: Contains the id BookStack has assigned to the new book.
• new_book.url: Contains the url to the new book in BookStack.

Create a page

Create a new page in a specific book in BookStack:

action: bookstack.create_page
data:
  book_id: 20
  name: My New Page
  markdown: |
    ## This is a sub title
    This is some text in the page
    ### This is a sub sub title
    This is some more text in the page
  tags:
    - name: home-automation
    - name: environment
      value: production
response_variable: new_page

After the action runs, the response_variable will contain all information about the page which the BookStack API returns. The information in the response can be used in following actions. Most useful are:

• new_page.id: Contains the id BookStack has assigned to the new page.
• new_page.url: Contains the url to the new book in BookStack.

Append to a page

Append additional contents to an existing page in BookStack:

action: bookstack.append_page
data:
  page_id: 5
  markdown: |
    ## This is a new title added
    This is some new content appended by Home Assistant.
  tags:
    - name: priority
      value: high

Additional content in either markdown or html will be appended to the bottom of the page. Any tags specified will be added to the page. Duplicate tags (i.e. those already assigned to the page) will be simply ignored. New tags will be added.

Caution

The BookStack API behaviour around HTML and Markdown content is limiting. If the page was created in markdown then the API will return both a markdown and HTML version of the page. If it was created in HTML then the API will only return a HTML version of the page and the markdown element will be blank. Because of this, if the action is configured with the markdown element then the integration will first check if the page has existing markdown content, and if not, the action call will fail.

Troubleshooting

Integration won't load

• Verify your BookStack URL is correct and includes the protocol (https:// or http://)
• Ensure your API token has sufficient permissions and hasn't expired
• Check Home Assistant logs for detailed error messages

Sensors show "Unavailable"

• BookStack instance may be offline or unreachable
• Check the Connectivity diagnostic sensor
• Verify network connectivity from Home Assistant to BookStack
• Check Home Assistant logs for connection errors

Per-shelf sensors not appearing

• Ensure "Enable per-shelf sensors" is checked in the integration options
• Check that you have at least one shelf created in BookStack
• Reload the integration after creating new shelves

Slow updates or timeouts

• Increase the scan interval if you have many shelves (each shelf requires multiple API calls)
• Per-shelf sensors with many books can be resource-intensive
• Consider disabling per-shelf sensors if you have >20 shelves

API Rate Limiting

Per-shelf sensors can be resource-intensive if you have lots of shelves in your BookStack instance. The integration makes the following API calls per update:

• Base stats: 5 calls (system, shelves, books, chapters, pages, users, images, attachments)
• Last updated page: 2 calls (list + detail)
• Per shelf (if enabled): 2-3 calls per shelf (list + detail + book details)

Consider a longer scan interval or disabling this feature if you have more than 20 shelves.

Support

• Report an issue
• BookStack Documentation
• Home Assistant Community

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• BookStack - The awesome knowledge base platform
• Home Assistant - Open source home automation

Possible future additions and improvements

The below are possible future additions and improvements to the integration. To add your own, please raise an issue describing the desired functionality.

• Submit integration for inclusion in HACS