Bookshelf is a simple wiki-like document organizer for use locally on one machine. Viewing is done through a web browser, and the content is generated statically. There are two types of documents: shelf documents which are generated from the convenient markdown format and can be viewed directly in the web browser, and ordinary documents (for example PDF, HTML, etc.) which the web browser treats in any way it likes.
The most important feature of Bookshelf is its simplicity: No web server is needed. There are no global files for configuration/caching/indexing etc. A complete document collection is simply represented as a directory structure containing the relevant documents. Bookshelves are modular in the sense that sub-directories can be moved arbitrarily within or between bookshelves without worrying about inconsistencies1. Documents are added simply by placing them within the directory structure.
The input to Bookshelf is a directory tree with shelf documents (extension .shelf) and ordinary documents (any other file). Running Bookshelf on the directory Shelf is done as follows:
bookshelf Shelf
This will (re-)generate the whole directory contents (see section Operation).
We can also supply some optional parameters:
bookshelf --css bookshelf.css --editor gedit Shelf
The first parameter tells Bookshelf which style sheet to use for the generated pages. The recommended style sheet for Bookshelf is bookshelf.css. The second parameter tells what editor to use when editing the source files. This command will appear in an edit/regenerate script at the end of each generated page.
Running Bookshelf without arguments results in the following message which shows the complete usage:
bookshelf [options] <source>
[-c,--css <CSS file>] Path or URL to CSS style sheet
[-e,--editor <editor command>] Command used for editing source files
[-n,--no-script] Do not display the edit/regenerate script
<source> Root directory of bookshelf to be generated
The markdown syntax is described here, and the extensions supported by Pandoc (the converter used internally by Bookshelf) are described here.
Bookshelf performs two main operations in a given directory:
name.shelf to the file name.shelf.html. In this process, any links to files of the form name.shelf get redirected to name.shelf.html.index.html at each directory node. This file contains links to the directory’s sub-directories and documents. The Meta information section describes how the document listing can be affected.For convenience, each generated HTML file displays a “script” for editing/regenerating the source file at the end. This can be turned off by providing the --no-script flag.
It is possible to exclude files or directories from being converted and indexed by using “ignore” files. To exclude the file name, simply add a file name.ignore in the same directory.
Warning: Any existing file with the extension .shelf.html or the name index.html are assumed to have been generated by previous runs of Bookshelf. Such files will first be removed2, and then possibly regenerated, so one should be careful not to have ordinary documents with such names.
Bookshelf checks that all local links (in shelf documents) are valid, and will issue warnings if this is not the case.
Pandoc’s markdown syntax allows the specification of “title blocks” containing information about document title, authors and date. If such information is provided for shelf documents, it will be included in the document listing for each directory.
Whenever a shelf document and an ordinary document have the same name, apart from extensions, the shelf document is assumed to contain information about the ordinary document. In this situation, we call the ordinary document the main document and the corresponding shelf document the info document. An info document will only appear as an “info” link next to its main document in directory listings. Further more, the info document may optionally specify meta information about the main document by including a section of the following form at the top of the markdown source:
Meta
====
* Title: Title of document
* Authors:
* Author number 1
* Author number 2
* etc.
* Date: Some string indicating date
* Comment: Some comment
This information will then be used when listing the ordinary document.
The contents in Documentation has been generated by Bookshelf. In addition to the current manual, it contains a sub-directory Test that demonstrates some of Bookshelf’s features. The source of the documentation directory can be found here.
The easiest way to install Bookshelf is using the Cabal install tool. Cabal install is available in the Haskell Platform.
Bookshelf can be installed directly from Hackage:
cabal install Bookshelf
Alternatively, it can be downloaded from its repository, and installed by running
cabal install
in the Bookshelf directory.
Links may of course be broken when sub-directories are moved, but this can often be prevented by appropriate use of relative and absolute links. Furthermore, broken local links will be detected when the page is generated. ↩
This process does not take any .ignore files into account, so, for example, the file name.shelf.html will be deleted regardless of whether the file name.shelf.html.ignore exists. ↩