bsimport

A Python tool for importing Markdown files to a Bookstack instance.

Important notice

This project is no longer maintained. I don't use Bookstack anymore so I'm not sure if it still works: if you have any feedback, please share it by opening an issue.

Motivation

I currently use Obsidian for all my note-taking needs. I wanted to test Bookstack with my existing notes, and since it has an API, I created this tool to import them.

I used Typer to create the CLI, and implemented my own incomplete wrapper of the API.

Features

• Import a single file or an entire directory:

  • A single file is imported as a page, so it will ask for the ID of the book you want to add the page to. You can list your accessible books with python -m bsimport list-books.
  • A directory is imported as a book: any Markdown files found directly inside will be imported as pages of this book.
    • If a subdirectory is found, it will be imported as a chapter, and any Markdown files inside it will be imported as pages of that chapter.
    • If a subdirectory of a subdirectory is found, it will be completely ignored, even if it contains Markdown files.

• Support for tags: Obsidian uses a YAML front matter to add tags and other information at the top of the page. Currently, only tags created with the format tags: [tag1, tag2, tag3] are supported. This means the following YAML list format is not supported:

  tags:
  - tag1
  - tag2
  - tag3

  • Additionally, any other front matter key such as aliases will be ignored.

• The API token and Bookstack URL are saved in a configuration file. You can get the path to the file with python -m bsimport where.

Usage

• Get the API token:

  • Login to your Bookstack instance.
  • Edit your profile.
  • At the bottom of the page, create a new token. Save both the ID and the secret.

• Install the package with:

  python3 -m pip install bsimport

• Run the init command:

  python -m bsimport init

  It will ask you for the token ID and secret, as well as the URL to your Bookstack.

• Then import your files with:

  python -m bsimport import /path/to/file

To modify the code

• Download or clone the code.

• (Optional but recommended) Create a virtual environment: see https://docs.python.org/3/library/venv.html. Example:

  python3 -m venv .venv

• Install the dependencies:

  python -m pip install -r requirements.txt -r dev-requirements.txt