Library Management 📚

1. 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:

• library catalogue that can host various different file formats (e.g. ebooks, a/v media, and zip files; see §⁄populating the library);
• catalogue search by Author, Title, or Tags;
• presentation of library 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 every entry.
• referencing library items in entries of this site via item id, and automating bibliographic citations.

2. Contribution workflow¶

For better library maintenance it is recommended to have single designated librarian. The optimal way to contribute to the library is by submitting a bibliographic collection exported via Zotero (as described in §⁄Export bibliography collection). This can be easily integrated with the existing library by the managing librarian.

3. Required software for library management¶

• www⁄Calibre: free & open source eBook management software available for Windows, OSX, and Linux.
• www⁄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).

4. Library integration outline¶

1. The library is maintained in www⁄Calibre.
2. The library is excluded from the Git repository of the site, because of its sub-optimal way of handling large non-text files (e.g. PDFs).
3. Adding items to the library can be done:
   1. directly to www⁄Calibre, or
   2. by loading a bibliography exported from www⁄Zotero via www⁄Accorder.
4. To update the library, using the command line tool www⁄Accorder:
   1. Create a portable version of the library.
   2. Create a library catalogue (JSON dictionary located at root/data/books/catalog.json)
5. Upload the library via rsync.

5. 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.¹

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.

5.1. 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.

5.2. Via Zotero¶

5.2.1. Export bibliography collection¶

To export items via www⁄Zotero do the following:

1. Select an item, multiple items, or a collection, with valid file attachments¹ which are stored locally (not on the Zotero cloud).²
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)

5.2.2. Import bibliography collection to Calibre (requires Accorder setup)¶

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

6. Building library standalone with Accorder¶

www⁄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 www⁄Zotero and including files) into Calibre.

6.1. 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

6.2. 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.

6.3. 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.

6.4. 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.

6.5. 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/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, www⁄Notepad++ for Windows, features the plugin JSTools that can auto-format JSON.

7. Deploy library¶

To deploy a library use www⁄Accorder to:

1. §⁄build a library standalone web app.

2. §⁄build a library catalogue.

3. Place the library catalogue at the folder data/books/ of the project, as in:

   /root/data/books/catalog.json
   

4. 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

8. 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 www⁄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:

Paul Coulton, Alan Hook, Petri Lankoski & Jussi Holopainen, 2017. bib⁄Games Design Research through Game Design Practice. Carnegie Mellon University: ETC Press.

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