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 Bookshelfexternal link 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 GoodReadsexternal link , which was looking very promising especially that they documented their API1. 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 templates2, 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 themeexternal link , install it firstexternal link .

  2. Clone PaperMod-bookshelf repoexternal link to your project:

  • as submodule (recommended)

    Add bookshelf theme to the Hugo site
    cd your-site-location
    git submodule add --depth=1 \ \

    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 \ \

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

Update hugo.yaml
  - PaperMod
  - PaperMod-bookshelf

Original theme should be first, followed up by extension.

  1. Create a page where books will be listed, for example content/ 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.

  1. Add first book, by calling:
Add example book for testing
hugo new -k book books/2024/my-first-book

  1. Run your page and check /bookshelf URL, usually: http://localhost:1313/bookshelfexternal link

If you’re unable to get it working, check exampleSiteexternal link 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:

Add book entry
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
  - 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:

    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:

  hidden: true

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

For more details, check the repo3.

Enjoyed? Buy Me a Coffee at