readinglist-js

A static site generator for your reading list

Installation

$ npm add readinglist-js

Usage

To generate your reading list website, you'll need a JSON book.json file. To display an avatar image in the rendered static site, you'll also need to provide an avatar.png file, which should live in the same directory as the generated output.

The Book file

The book file is a JSON file with two keys: a meta key, containing an object with configuration options, and a books key, containing an array of JSON objects. The structure should look like this:

{
  "meta": {
    ...
  },
  "books": [
    ...
  ]
}

The meta Object

The structure of the meta object looks like this:

Key	Value
name	Your name. Displayed in the header of the generated site.
email	(Currently unused) Your email address.
website	(Currently unused) Your website.

All of the values are required.

JSON Feed Output

You can optionally have the generator also output a JSON Feed file by adding a feed key to the meta configuation. The feed object looks like this:

Key	Value
title	A title for your feed. May be used by feed readers when displaying your feed. See the JSON Feed spec for more information.
url	The URL to your hosted JSON Feed output. Because this is used by feed readers for discovery, it must be a fully-qualified URL, and readinglist.js can't predict where you'll host the file, you have to provide it yourself.
avatarUrl	(Optional) The URL to an icon that represents your feed. This URL is used by feed readers to display your feed, and must be a fully-qualified URL. See the JSON Feed spec for more information.

The book object

The structure of the book object looks like this:

Key	Type	Value
title	string	The title of the book
author	string	The author of the book
year	int	The year you read the book (not the year it was published). If year is set, current must not be set.
current	boolean	Set current to true to mark a book you're currently reading. If current is set, year must not be set.
link	string	(Optional) A link to the book's website or Amazon page. If provided, the book's title will be a link to this URL in the output.
recommended	boolean	(Optional) If set to true or false, will mark a book as recommended (or not) in the output template. Ignored otherwise.
finished	boolean	(Optional) If set to false, marks the book as "Did not Finish" in the output template. Ignored otherwise.

Running the generator

To generate your site, run the following command:

npx reading-list -b <path to your books.json file> -o <path to your output directory>

Sample output

See reading.joshtompkins.com for a sample site running the default theme.

Development

Useful yarn Commands	Purpose
install	Installs local dependencies.
test	Runs local tests.
sample	Do a test run against the sample books file in the test directory, for local testing.
link	Prepares this package to be installed locally for inclusion in other projects. In the other project, run link readinglist-js to install.
global add $PWD	Installs this package globally to your system, allowing you to test the CLI. Note that the contents of the repo are not watched, so if you make changes, you'll need to run this command again.
publish	Push the latest version of the package to the global NPM repository. You'll need credentials to do this. This command creates local git tags to mark the release version; don't forget to push these to the remote origin.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jtompkins/readinglist.js.