jgdr/content/article/int-library.md

---
title: "Library Management 📚"
date: "2023-06-29T18:59:19+03:00"
author: "anybody"
contributors: 
draft: false 
keywords:
  - internal
  - library 
  - journal management
abstract: |
  (Internal) Library management guide for Sandpoints projects.
---

[Accorder]: https://pypi.org/project/accorder/ "Accorder at pypi.org."
[Zotero]: https://www.zotero.org/ "Zotero.org; free, open source and cross-platform citation management software."
[Calibre]: https://calibre-ebook.com/ "Calibre-ebook.com; free, open source and cross-platform eBook management software."
[Library]: /library/BROWSE_LIBRARY.html "Project library."
[Accorder book extensions]: https://gitlab.com/marcellmars/accorder/-/blob/master/accorder/utils/bibtex.py#L55 "Accorder supported book extensions (Gitlab)"

# Introduction 
Sandpoints is designed to be integrated with a library. The library is accessible via the red button at the top right corner of any content page, or at [Library][] . Key features of the library include:  
- hosting collections maintained by different librarians; 
- library catalogue search by Author, Title, or Tags;  
- presentation of catalogue by book covers (default) or as list (select from top of the page); 
- basic item metadata as well as the Librarian's description of an entry. 
- referencing library items in entries of this site, and automating bibliographic citation via item id. 

# Required software for library management

- [Calibre][]: free & open source eBook management software available for Windows, OSX, and Linux. 
- [Accorder][]: a Python command line tool -- installation instructions below.
- A command line interface (CLI; such as *Windows PowerShell*, *Git Bash*, or *Terminal* or *iTerm2* for macOS). 

# Populating the library 

Assuming you have a Calibre library running, you can add items from a range of file formats supported both by Calibre and Accorder. These are: `pdf, epub, mobi, azw, azw3, cbz, chm, djvu, doc, docx, fb2, htmlz, mbp, md, txt, zip`.[^vfa]  

Note that a Calibre library entry can have *multiple different files associated with it* (for example both a pdf and an epub), however, it cannot have two files of the same format. 

## Via Calibre 

1. Click `Add books`, or drag and drop a file (e.g. pdf, epub, zip) to Calibre. 
2. Select the item and click `Edit metadata`, or press `e`. 
3. Add/correct the item **title**.
4. Add/correct the name of the **author(s)**. Author names are entered as in `Name Surname`. Multiple authors are separated by ampersand as in `Jane Doe & John Doe`. 
5. Automatically download metadata. Calibre should be able to download metadata automatically from online databases (this works mostly for commercial books). 
	1. With the author names and book title in place (ideally also the `ISBN` -- see step 7), . Click `Download metadata` or press `d`. 
	2. Calibre will find available metadata sets, which might include book cover and item description or review. Check if the 
	3. If Calibre fails to find available metadata, try to add the book ISBN and try again. Otherwise 
6. Add **identifiers** such as ISBN, or DOI in the field `Ids`, as in `isbn:12345674896`. In case of multiple ids separate them with a semicolon(`;`).  
7. Add **keywords** separated by commas, as in `game design, monograph`. Try to enter adequate keywords. If the item metadata were downloaded automatically review the keywords, as they are usually generic.  
8. Add **publisher**. 
9. Add **publication date** in the field `published`. 
10. Make sure that the item has a **book cover**. If not either click `Download cover` (which will try to find a cover from online databases), or click `Generate cover` to create one based on the item's metadata. 
11. Click OK to save these changes. 

## Via Zotero (requires Accorder setup)

To export items via [Zotero][] do the following: 
1. Select an item, multiple items, or a collection, with *valid file attachments*[^vfa] which are *stored locally* (not on the Zotero cloud).[^local]
2. Right click and select `Export Item(s)`. 
3. In the new dialogue select a BibTeX format and check the box `Export Files`. 
4. Click OK, and select destination and filename (e.g. `mycollection.bib`)

[^vfa]: For valid file attachments see [Accorder book extensions][]. 

[^local]: To check if your Zotero file attachments are stored locally double click on a given item, to open its attachment. If the item is on the cloud Zotero will automatically download the associated file to your local database. 

To import the Zotero collection to Calibre do (for setting up accorder profiles see next section):
```
accorder build -b path/to/zotero/export/mycollection/mycollection.bib profile-name
```

# Building library standalone with Accorder 


[Accorder][] is a Python command line tool developed by Marcell Mars used for amateur librarianship. 
It's main features are: 
- building a standalone portable web app version of a Calibre library accessible via `http`, 
- compiling a JSON catalogue of a standalone library, 
- transferring bibliographic items within `.bib` files (e.g. exported from [Zotero][] and including files) into Calibre.  

## Install Accorder 
To install accorder open a terminal and do: 
```
pip3 install accorder
```
To upgrade accorder, do: 
```
pip3 install --upgrade accorder
```
To check the version of your accorder installation do: 
```
accorder --version
```
For a list and description of accorder commands do: 
```
accorder --help
```

## Accorder profiles

Accorder requires to setup a `profile` that is associated with: 
1. a librarian, and 
2. a local Calibre library directory. 

To show existing accorder profiles, do: 
```
accorder configuration --show 
```

If an accorder profile was already setup, the previous command will output: 
```
..PROFILE: profile-name
....LIBRARIAN: librarians-name
....CALIBRE LIBRARY: /path/to/calibre/library/
```
It will also show the path of the *accorder.ini* file with configuration profile information. 

## Create accorder configuration profile 

To create a new accorder profile do: 
```
accorder build -d /path/to/calibre/library/ -l librarians-name profile-name
```

This will setup a new profile and also build a standalone web app of the library. 
The profile should now be visible in `accorder configuration -s`. 
To edit elements of a profile configuration follow instructions in `accorder configuration --help`. 

## Build a portable library 

With accorder installed and a profile setup, to build a standalone web app of the library do: 
```
accorder build profile-name
```

This will generate a portable version of the Calibre library by adding in the library directory: 
1. a `BROWSE_LIBRARY.html` file, and 
2. a folder titled `static` with necessary dependencies. 

## Build library catalogue

To build a library catalogue that allows referencing library items from Sandpoints do: 

```
accorder build -j /path/to/export/catalog.json profile-name
```
This command will build the library catalogue in JSON format. The catalogue includes a unique ID and metadata fields for every item of the library. 

The file *should be named* `catalog.json`, and *should be placed* inside a Sandpoints project in the directory `root/data/books/catalog.json`. Or, it can be directly compiled at that directory: 

```
accorder build -j /path/to/root/dir/data/books/catalog.json profile-name
```

Note: The catalogue file can be opened and viewed with any text editor. It is formatted in a single line. Some text editors feature tools that can auto-format JSON files so that they are more easily readable. For example, [Notepad++][] for Windows, features the plugin *JSTools* that can auto-format JSON. 

[Notepad++]: https://notepad-plus-plus.org/downloads/ "Notepad++ is a free and open-source text editor for Windows."

# Deploy library 

To deploy a library firstly use accorder to 
- [build a library standalone web app](#build-a-portable-library), and
- [build a library catalogue](#build-library-catalogue). 

1. Place the library catalogue at the folder `data/books/` of the project, as in: 
   ```
   /root/data/books/catalog.json
   ```
2. Build library standalone web app, and copy the entire contents of the Calibre library directory (including the `static` folder and `BROWSE_LIBRARY.html`) to ... 
   > For local projects the library can be copied to:
   > ```
   > /root/content/library/
   > ```
   > so that `BROWSE_LIBRARY.html` is at: `root/content/library/BROWSE_LIBRARY.html`

# Link library item inside Sandpoints articles

To reference a library item inside a Markdown entry of this project do: 
```
![Link caption](bib:the-book-id). 
```

`the-book-id` is a placeholder for the unique id of a library item, which is in the style of `625e5562-38bc-4497-adaa-5142ef810c4a`. 

To find the unique ID of a library item, do either of the following: 
- Open the library catalogue (`/root/data/books/catalog.json`) with a text editor such as [Notepad++][]. Search for the book that you want to reference, and copy its `_id` field. 
- Open the [Library][] find the item you want to reference, and copy the last part of it's URL after `.../book/`. 

The following example links to the library item at: `.../library/BROWSE_LIBRARY.html#/book/3ea44269-47eb-468b-906e-3104398aaa07` 
Thus, the item unique id is: `3ea44269-47eb-468b-906e-3104398aaa07`. 

*Formatting*:
```
![](bib:62cdc920-998c-4563-a656-1e874d280101)
```

*Appearance*: 

![](bib:62cdc920-998c-4563-a656-1e874d280101)

*Note: To overwrite the citation text that is automatically generated by the above syntax add some custom text in the square brackets.*