Building openring with Jekyll Build

2022-12-02

I think it’s great when bloggers post their own personal “reading list” of blogs they themselves follow. Whether this is a customized Blogroll page or footnotes in their individual articles, I find it really helpful to find more interesting content on the “indie” web. This isn’t a new concept by any means, but I wanted something a little more “dynamic”¹ for my own blog.

After some digging I came across openring and it’s great. Fully customizable, lightweight and completely open source. What more could you ask for?

So, I thought others might be interested in how I’ve implemented openring through my own Jekyll build system.

Installing openring

You can pull the project directly via SourceHut if you wish, but I would recommend installing through your default package manager. I’m running Arch, so for me it was as simple as running:

yay -S openring

That’s it. I now have full local access to openring!

Jekyll Includes

You could setup a whole new directory specifically for your openring files, but that seems like overkill. Instead, we will simply add two new files to our existing _includes directory. We will name these files openring-in.html and openring-out.html.

openring-in.html Contents

<!-- License-Id: CC0-1.0 -->
<section class="webring">
  <h3>Articles from blogs I follow around the world wide web</h3>
  <section class="articles">
    {{range .Articles}}
    <div class="article">
      <h4 class="title">
        <a href="{{.Link}}"  rel="noopener">{{.Title}}</a>
      </h4>
      <p class="summary">{{.Summary}}</p>
      <small class="source">
        via <a href="{{.SourceLink}}">{{.SourceTitle}}</a>
      </small>
      <small class="date">{{.Date | datef "January 2, 2006"}}</small>
    </div>
    {{end}}
  </section>
  <p class="attribution">
    Generated by
    <a href="https://git.sr.ht/~sircmpwn/openring">openring</a>
  </p>
</section>
<style>
.webring .articles {
  display: flex;
  flex-wrap: wrap;
  margin: -0.5rem;
}
.webring .title {
  margin: 0;
}
.webring .article {
  flex: 1 1 0;
  display: flex;
  flex-direction: column;
  margin: 0.5rem;
  padding: 0.5rem;
  background: #eee;
  min-width: 10rem;
}
.webring .summary {
  font-size: 0.8rem;
  flex: 1 1 0;
}
.webring .attribution {
  text-align: right;
  font-size: 0.8rem;
  color: #555;
}
</style>

Sidenote: You will get minor Liquid Syntax warnings in the console when running your website via serve or build. I don’t really mind those warnings but if you do, feel free to move these files out into their own sub-directory in your project folder.

openring-out.html Contents

This will generate itself for us every time we rebuild our Jekyll website. It is important to note that any changes you make in this file will be overwritten the next time you rebuild! All custom styling or layout changes should be made in the openring-in.html file.

Our “New” Build Script

To simplify things, we are going to place our main commands in a single build script in the root directory of our Jekyll project. For my personal blog, I’ve named this file build-site.sh. I know - I’m extremely creative.

Place the following inside that file:

openring \
  -s https://example.com/feed.xml \
  -s https://example.com/feed.xml \
  -s https://example.com/feed.xml \
  < _includes/openring-in.html \
  > _includes/openring-out.html
bundle exec jekyll build

Edit _config.yml

Next we need to make sure we exclude our new build-site script file, since we really don’t need that pushed up to the main server:

# Includes / Excludes
exclude:
  - build-site.sh

Almost Done…

Now you just need to decide where you want your openring feed outputs to render. For this example, we will place them at the bottom of every blog post inside the _layouts/post.html file, like so:

{% raw %}{% include openring-out.html %}{% endraw %}

Build It & They Will Come

This next step is only for those using SourceHut Pages to build and host their websites. If you use a different platform (ie Netlify, Vercel, GitHub Pages) the concept should be similar but will most likely require more tweaking on your end. Just a fair warning.

I won’t go into great detail about build script for SourceHut Pages, but feel free to take a look at my very own build file for this website. That should work out-of-the-box for most standard Jekyll websites. (Just be sure to edit with your own details!)

That’s it. You now have links to blogs you enjoy that will update with each build. Of course, the “latest” blog posts shown will become out-of-date if you don’t blog (or at least re-build your website) on a regular basis. But for me, I see this as a good motivator to keep pushing out content!

Happy sharing!