Create a Virtual Bookshelf with Hugo and PaperMod

TL;DR
If you don’t care about my reasoning, just jump to the description of installation and usage . Click here for a demo .

I try to read at least one book each month. It’s not much, but that’s what I can afford. I read a lot of technical books, building my technical skill set, but a lot of random topics from business, psychology or fantasy.

It happen to me many times that when I’ve been asked about specific book, I couldn’t remember “Where did I read it?” or “What was the book title?”. Some day I accidentally passed through Dave’s Rupert blog and his Bookshelf  and I loved it! I have a blog, so great place to collect and share, with easy access from anywhere - why not to use it?

I didn’t want to add all those books manually as it felt a little bit an overkill, so I was looking for some kind of social network about books, where I could add books easily and just auto-generate the listing on my blog via API calls. I found GoodReads  , which was looking very promising especially that they documented their API¹. There was just a little but…

I’ve been looking through few other alternatives, but didn’t found a good replacement 😦

Then, I have to add it to my blog. There were two ways I could do it:

1. Create a blog post per book and extract them on one sub-page.
2. Use Hugo’s data templates², so store Books metadata in YAML/JSON and generate page from it.

Second idea was tempting, but what if I’d like to add a book review or short summary of it’s content? It’s just better to go with the blog post per book. It won’t take too much time to add it and I will have some obligation to write summary. It was decided.

Bookshelf Theme installation and usage

1. It requires original PaperMod theme  , install it first  .

2. Clone PaperMod-bookshelf repo  to your project:

• as submodule (recommended)

  Add bookshelf theme to the Hugo site

  cd your-site-location
  
  git submodule add --depth=1 \
    https://github.com/tgagor/hugo-PaperMod-bookshelf.git \
    themes/PaperMod-bookshelf
  

  
  

  You might need to initialize any uninitialized submodules in the repository and then recursively update all submodules to their latest versions to make it fully available:

  Update git submodules

  git submodule update --init --recursive
  

  
  

• or by just cloning

  Add bookshelf theme to the Hugo site

  cd your-site-location
  
  git clone --depth=1 \
    https://github.com/tgagor/hugo-PaperMod-bookshelf.git \
    themes/PaperMod-bookshelf
  

  
  

To activate the bookshelf, update config.yaml or hugo.yaml:

theme:
  - PaperMod
  - PaperMod-bookshelf

Original theme should be first, followed up by extension.

3. Create a page where books will be listed, for example content/bookshelf.md with such content:

---
title: My Bookshelf
layout: bookshelf
url: /bookshelf
---

Of course you can amend the url and title. layout field is what identifies how it should be filled, so have to stay like that.

5. Add first book, by calling:

hugo new -k book books/2024/my-first-book

6. Run your page and check /bookshelf URL, usually: http://localhost:1313/bookshelf 

If you’re unable to get it working, check exampleSite  directory.

Adding books

Theme rely on posts in the content/books directory, to keep them outside of the typical posts. You might prefer other location.

To add new book, just create a new blog post of kind book:

hugo new -k book books/2024/new-book

It will generate “a blog post” describing the book, with additional fields which are required to make the mechanism work. They are:

title: Book's title
sub_title: Book's sub title
date: Date when you read the book
book_authors:
  - A list of
  - All the authors
categories: # used for finding the books among other posts
  - Book
tags:       # categories of books, use/extend as you want
  - Biography
  - Business
  - Fantasy
  - Finance
  - Graphic Novel
  - Leadership
  - Management
  - Mystery
  - Politics
  - Pop-sci
  - Psychology
  - Security
  - Sci-fi
  - Science
  - Sociology
  - Technology
  - Trading
book_rating: 5  # your raging 1-5 stars

Archetype adds a shortcode book call, which I preferred over typical book cover. It add’s a nice header with book’s cover and can provide links to few websites (reviews, affiliate links, whatever).

Rest is up to you. You can write a review or whatever 😉

Considerations on configuration

Configuration related to the cover in the original theme might impact how books are presented. My config looks like that:

params:
  cover:
    responsiveImages: true
    hidden: false # hide everywhere but not in structured data
    hiddenInList: false # hide on list pages and home

If you use hiddenInSingle: false, then book posts would always show a huge cover image as a cover. I didn’t like it. It’s best to leave this setting not configured.

Then to hide the covers for books I hide them in every post by:

cover:
  hidden: true

That’s my preference, feel free to play settings according to your needs.

For more details, check the repo³.

Enjoyed?