Not so fast, there, fella

Survey says: I jumped the gun on that two-feeds strategy I mentioned in the previous post.

2022-12-10

Latest commit: 69b81294, 2023-01-07
1,169 words • Reading time: 6 minutes

Sometimes a learning experience is also a humbling experience. Such was the case with the aftermath of my previous post.

In case you didn’t read that one, it was my explanation of how I was now using this site’s RSS and JSON content feeds: i.e., the former with only the title and description of each post and the latter also with the post’s full content. I thought I’d cooked up a best-of-both-worlds approach for my feeds-savvy readers, since they could choose the content feed which best suited their wishes.

But I soon learned it wasn’t that simple.

I heard from folks saying that it wasn’t a safe assumption that everyone could choose either kind of feed, with the JSON Feed format being less widely supported than the ancient-in-Internet-time RSS. While my own research had shown JSON feeds are available via the vast majority of feed-reader apps and services, “the vast majority” is not the same as “one hundred percent.”

Some also told me that, regardless of feed type (a choice of which, a few respondents suggested, required more knowledge than a non-trivial number of feed customers might have), they fervently believed it should be one way or the other, not both. Those comments, in particular, led me to conduct a poll on Mastodon, asking whether RSS reader users preferred that a feed item provide the full text of an article or merely an excerpt from it. It got 646 responses, and here’s how it turned out:

ResponseResult
Full text72.0%
Excerpt20.4%
No preference7.6%

Not exactly too close to call, eh?

“Full article text” took a substantial lead almost immediately and, especially once the quantity of voters grew large enough to provide some degree of statistical significance, never lost it throughout the poll’s twenty-four-hour life. I suppose that’s what I get for changing the feeds and writing the previous post before doing the poll. D’oh.

But . . .

Even though “Article excerpt” came in a very poor second, a number of its adherents told me that only that approach worked with certain device setups, bandwidth constraints, and so forth — not to mention people’s tight schedules. So, while it was clear that I needed to give the “Full article text” side its due in configuring my feeds, I also saw that I couldn’t simply ignore the minority and go back to having only full-text feeds. I had to do better.

As a result, here’s what I’ve done with the site (but see also the Update at the very bottom of this post):

  • There are now four feeds, two in RSS (actually Atom) format1 and two in JSON format. Each format has one primary feed and one secondary feed. All four are linked from the “Contact” page.
  • The two primary feeds are still (a.) at their previous locations (index.xml and index.json, respectively) and (b.) linked from distinctive icons in the footer. Each primary feed once again includes the full content of each post, as was these feeds’ setup prior to my turned-out-to-be-temporary shakeup of the last couple of days.
  • Each of the two secondary feeds (either index-excerpts.xml or index-excerpts.json) includes only each post’s title, description, and — you guessed it — an excerpt.2

I think this is about as close as I can come to making everyone happy on this particular score. Guess I’ll find out.


Addendum for Hugo users, 2022-12-14

Important: This corrects some erroneous information I’d added to this post earlier today, in which I confused redirects with moves. I apologize for the goof!
Also, I provided some additional details on 2022-12-19, followed by a further update on 2022-12-26.

If you want to have a feeds setup as described above in a Hugo site, you’ll have to jump through some hoops. This is because, as nearly as I can tell through researching the subject, Hugo allows only one feed (per format) per section. For example, the home page — typically the “owner” of a Hugo site’s feed(s) — can have one RSS/Atom feed and one JSON feed, but that’s it. To have multiple feeds of a given format, set up each additional set of feeds in a separate section.

Let’s say you use a posts section to “own” your index-excerpts.xml and index-excerpts.json feed files, by adding appropriate .json and .xml layouts3 there, each named according to Hugo lookup rules:

 layouts/
 └─ posts/
    ├── section.json
    ├── section.xml

. . . which would cause Hugo to generate /posts/index.json and /posts/index.xml, respectively, for your site. But those aren’t the top-level links you probably would prefer (well, definitely not the ones I would prefer), and my research also indicates Hugo doesn’t offer a way to move the files. That means you’ll need to do so yourself during the build process.

If you use a Jamstack-savvy host such as Cloudflare Pages, Netlify, or Vercel, you can add file-moving commands to your overall build command. Let’s say your usual Hugo build command is hugo; the following would build the site and move the files:

hugo && mv public/posts/index.xml public/index-excerpts.xml && mv public/posts/index.json public/index-excerpts.json

If you use CI/CD to build your Hugo site, you can add a step after the hugo site-building command that will move those feed files to where they need to be. For a GitHub Action, that could be:

      - name: Move feeds
        run: |
          mv public/posts/index.xml public/index-excerpts.xml
          mv public/posts/index.json public/index-excerpts.json          

. . . while, if using a GitLab CI/CD pipeline, you could do this within the script section:

    - mv public/posts/index.xml public/index-excerpts.xml
    - mv public/posts/index.json public/index-excerpts.json

Finally, if you build manuallyi.e., you copy your Hugo-generated public/ folder to the appropriate place on your host — just manipulate those files as follows before you copy that folder:

  • Move public/posts/index.xml to public/ and rename the file index-excerpts.xml, so that it will be public/index-excerpts.xml.
  • Move public/posts/index.json to public/ and rename the file index-excerpts.json, so that it will be public/index-excerpts.json.

Update, 2022-12-26: After encountering some minor but apparently intractable issues with the JSON version of the excerpts-only feed (the issues appeared in testing with both Eleventy and Hugo, and thus appeared to be SSG-agnostic), I have now killed that feed and no longer link to it from the contacts page. The RSS/Atom excerpts-only feed does remain intact — as do both the full-text RSS/Atom and JSON feeds, of course.


  1. I chose to go with Atom after further research, during which I was particularly convinced by “Atom > RSS: Why We Should Just Call Them ‘Feeds’ Instead of ‘RSS’ Feeds” by Daniel Miessler (and other articles like it). It’s also worth noting that the documentation for Eleventy’s official RSS plugin chiefly recommends using Atom. On the other hand, Hugo’s default feeds template uses RSS but you can use an Atom template instead, such as what’s recommended in “Hugo Atom Syndication XML Template (Better RSS)” by Jhaura Wachsman↩︎

  2. Credit where credit’s due for my Eleventy repo in particular: to code for the excerpts and then convert them into Markdown for processing at build time, I relied heavily on “Customize front matter parsing” in the Eleventy documentation and “Replicating Jekyll’s markdownify filter in Nunjucks with Eleventy” by Ed Johnson-Williams↩︎

  3. As of 2022-12-14, the Hugo version of my site repo has examples of such layouts for both RSS/Atom and JSON formats. ↩︎

Next: Hugo-like archetypes in other SSGs, take two

Previous: Why have both RSS and JSON feeds?