# bsimport
A Python tool for importing Markdown files to a
[Bookstack](https://www.bookstackapp.com) 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](https://obsidian.md/) 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](https://typer.tiangolo.com/) 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](https://help.obsidian.md/Advanced+topics/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:
```YAML
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:
```bash
python3 -m pip install bsimport
```
- Run the `init` command:
```bash
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:
```bash
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:
```bash
python3 -m venv .venv
```
- Install the dependencies:
```bash
python -m pip install -r requirements.txt -r dev-requirements.txt
```
Raw data
{
"_id": null,
"home_page": "https://github.com/JulioLoayzaM/bsimport",
"name": "bsimport",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "bookstack,import,markdown",
"author": "JulioLoayzaM",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/e1/2f/04192fe0ac01b51f0cae9e586484a396bbd238f99aabca92278ecf4fb26b/bsimport-0.1.1.tar.gz",
"platform": "any",
"description": "# bsimport\n\nA Python tool for importing Markdown files to a\n[Bookstack](https://www.bookstackapp.com) instance.\n\n## Important notice\n\nThis project is no longer maintained. I don't use Bookstack anymore so I'm not\nsure if it still works: if you have any feedback, please share it by opening an\nissue.\n\n## Motivation\n\nI currently use [Obsidian](https://obsidian.md/) for all my note-taking needs.\nI wanted to test Bookstack with my existing notes, and since it has an API, I\ncreated this tool to import them.\n\nI used [Typer](https://typer.tiangolo.com/) to create the CLI, and implemented\nmy own incomplete wrapper of the API.\n\n## Features\n\n- Import a single file or an entire directory:\n - A single file is imported as a page, so it will ask for the ID of the book\n you want to add the page to. You can list your accessible books with\n `python -m bsimport list-books`.\n - A directory is imported as a book: any Markdown files found directly\n inside will be imported as pages of this book.\n - If a subdirectory is found, it will be imported as a chapter, and any\n Markdown files inside it will be imported as pages of that chapter.\n - If a subdirectory of a subdirectory is found, it will be completely\n ignored, even if it contains Markdown files.\n\n- Support for tags: Obsidian uses a [YAML front\n matter](https://help.obsidian.md/Advanced+topics/YAML+front+matter) to add\n tags and other information at the top of the page. Currently, only tags\n created with the format `tags: [tag1, tag2, tag3]` are supported. This means\n the following YAML list format **is not** supported:\n ```YAML\n tags:\n - tag1\n - tag2\n - tag3\n ```\n - Additionally, any other front matter key such as `aliases` will be ignored.\n\n- The API token and Bookstack URL are saved in a configuration file. You can get\n the path to the file with `python -m bsimport where`.\n\n## Usage\n\n- Get the API token:\n - Login to your Bookstack instance.\n - Edit your profile.\n - At the bottom of the page, create a new token.\n Save both the ID and the secret.\n\n- Install the package with:\n ```bash\n python3 -m pip install bsimport\n ```\n\n- Run the `init` command:\n ```bash\n python -m bsimport init\n ```\n It will ask you for the token ID and secret, as well as the URL to your\n Bookstack.\n\n- Then import your files with:\n ```bash\n python -m bsimport import /path/to/file\n ```\n\n## To modify the code\n\n- Download or clone the code.\n\n- (Optional but recommended) Create a virtual environment: see\n https://docs.python.org/3/library/venv.html.\n Example:\n ```bash\n python3 -m venv .venv\n ```\n\n- Install the dependencies:\n ```bash\n python -m pip install -r requirements.txt -r dev-requirements.txt\n ```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool for importing Markdown files to a Bookstack instance.",
"version": "0.1.1",
"split_keywords": [
"bookstack",
"import",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "c36f1f96231641b44d2c91972b4f655a",
"sha256": "4f98ca9582916ec712aa4d705144613cb70526ea897bbdd2ef389310993afb53"
},
"downloads": -1,
"filename": "bsimport-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c36f1f96231641b44d2c91972b4f655a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 11668,
"upload_time": "2022-12-21T15:00:24",
"upload_time_iso_8601": "2022-12-21T15:00:24.750141Z",
"url": "https://files.pythonhosted.org/packages/77/0c/55c2d4b88c0816f7ae545cd8246efa53b351af41e29bc51276edffbbc9c7/bsimport-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "abcf6f32f9abf745e43f80fc9555aa9a",
"sha256": "71e5e384e604aab15fe467c193431bdccbb4c558300fcc861bb2b251f4b0c607"
},
"downloads": -1,
"filename": "bsimport-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "abcf6f32f9abf745e43f80fc9555aa9a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11181,
"upload_time": "2022-12-21T15:00:26",
"upload_time_iso_8601": "2022-12-21T15:00:26.288143Z",
"url": "https://files.pythonhosted.org/packages/e1/2f/04192fe0ac01b51f0cae9e586484a396bbd238f99aabca92278ecf4fb26b/bsimport-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-21 15:00:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "JulioLoayzaM",
"github_project": "bsimport",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "typer",
"specs": []
}
],
"lcname": "bsimport"
}
JSON
