Building a reading list with Jekyll data files

I transitioned by previous book notes section to a new reading list section. Why?

I read a lot of fiction and don’t tend to take notes on it
I wanted to keep a list of books I’ve finished.
The book notes was not a great medium for doing #2. Writing the full set of notes was a pretty big barrier most of the time and I tended to go a few months at a time without updating the page, creating a large backlog.
I came across Frank Chimero’s reading page and loved it. I also noticed that James Somers takes a similar approach with just listing the books out.

So, I decided to implement Frank Chimero’s design with my own reading list.

Instead of just hardcoding them in a page and repeating tons of HTML for the rest of my life, I decided to put the reading list in a Jekyll data file (I chose yaml) that I could easily add to and make a simple template to output.

First, I started with my previous book notes section. Since they were stored in a Jekyll Collection, I was able to write a quick Liquid for loop to generate most of my list for me. But I didn’t want to: include a full star rating, just a recommended star. So I chose to star books that I rated 5/5:

{% assign reviews = site.book_reviews | sort: "date" | reverse %}
{% for review in reviews %}

- title: "{{ review.title }}"
  author: {{ review.author }}
  link: {{ review.book-link }}
  star: {% if review.stars == 5 %}yes{% else %}no{% endif %}

{% endfor %}

The result looked like this:

- title: "Stories of Your Life and Others"
  author: Ted Chiang
  link: http://amzn.to/2Ghql7a
  star: yes

- title: "A Burglar's Guide to the City"
  author: Geoff Manaugh
  link: http://amzn.to/2rElHgb

- title: "The Story of Sushi: An Unlikely Saga of Raw Fish and Rice"
  author: Trevor Corson
  link: http://amzn.to/2DAvzct

- title: "The Island at the Center of the World: The Epic Story of Dutch Manhattan and the Forgotten Colony That Shaped America"
  author: Russell Shorto
  link: http://amzn.to/2yqLmaE
  star: yes

Awesome! That spit me out a list of everything I’ve written book notes for. Since it is sorted by date in reverse chronological order, it was quick for me to manually break it up by year:

 - year: "2019"
    books:
      - title: The Summer Book
        author: Tove Jansson
        link: https://amzn.to/2ZMtUuC
        star: yes

      - title: "The Last Pirate of New York"
        author: Rich Cohen
        link: https://amzn.to/34h0Oa3
        star: yes

      - title: "Fall; or, Dodge in Hell"
        author: Neal Stephenson
        link: https://www.amazon.com/Fall-Dodge-Hell-Neal-Stephenson/dp/006245871X
        star: yes

- year: "2018"
    books:
      - title: "The World is a Narrow Bridge"
        author: Aaron Thier
        link: https://amzn.to/2PK3OZc

      - title: "Fashion Climbing"
        author: Bill Cunningham
        link: https://amzn.to/2PJqkgz

      - title: "Cape Cod"
        author: Henry David Thoreau
        link: https://amzn.to/2ZIISBV

      - title: "The Outermost House"
        author: Henry Beston
        link: https://amzn.to/2MOf3hb
        star: yes

Excellent. Two more steps:

I want a “last updated” key so I only have to update one file. That means I need to nest the years under a parent key in order to access them.
I need to manually add the books that weren’t in my notes but I know I read. This took me a few hours to get the books, authors, and links.

Once I added the “last updated” key, the yaml structure looked like this:

lastupdate: September 3, 2019
list:
  - year: "2019"
    books:
      - title: The Summer Book
        author: Tove Jansson
        link: https://amzn.to/2ZMtUuC
        star: yes

      - title: "The Last Pirate of New York"
        author: Rich Cohen
        link: https://amzn.to/34h0Oa3
        star: yes

      - title: "Fall; or, Dodge in Hell"
        author: Neal Stephenson
        link: https://www.amazon.com/Fall-Dodge-Hell-Neal-Stephenson/dp/006245871X
        star: yes

      - title: The Boatbuilder
        author: Daniel Gumbiner
        link: https://amzn.to/2Lgvh0l

  - year: "2018"
      books:
        - title: "The World is a Narrow Bridge"
          author: Aaron Thier
          link: https://amzn.to/2PK3OZc

        - title: "Fashion Climbing"
          author: Bill Cunningham
          link: https://amzn.to/2PJqkgz

        - title: "Cape Cod"
          author: Henry David Thoreau
          link: https://amzn.to/2ZIISBV

        - title: "The Outermost House"
          author: Henry Beston
          link: https://amzn.to/2MOf3hb
          star: yes

Here’s how I loop through that data to create my reading page:

{% for entry in site.data.reading.list %}

  <div class="year-container">
    <div class="year">
      <h4>{{entry.year}}</h4>
      <div class="number">{{entry.books | size}} books</div>
    </div>
    <div class="books">
      <ul class="reading-list {{entry.year}}">
        {% for book in entry.books %}
          <li>
            <a href="{{book.link}}" alt="_blank" rel="nofollow noopener">{{book.title}}</a> <span class="author">by {{book.author}}</span>{% if book.star %}<span class="star">★</span>{% endif %}
          </li>
        {% endfor %}
      </ul>
    </div>
  </div>
  
{% endfor %}

Note that {{entry.books | size}} line: This is what outputs the number of books I’ve read in a particular year by spitting out the size of the books array. This is one of the big benefits of using a data file instead of hardcoded HTML or markdown. Just add a new book and everything else updates itself. Plus, I can use the data file for other things later if I so choose.

Here is the result:

reading list

You can check it out over at the reading list page, or you can see the code over at my Jekyll Tools Github repository.

If you liked my book notes, don’t worry. They aren’t going anywhere. I’m keeping the pages up for posterity, but I’m not updating them any more.

Chuck Grimmett

Hi, I'm Chuck Grimmett.

Building a reading list with Jekyll data files