JSON Feed

This week, Manton Reece and Brett Simmons, two tech bloggers I’ve been reading for a long time, launch JSON Feed, in their own words:

The JSON Feed format is a pragmatic syndication format, like RSS and Atom, but with one big difference: it’s JSON instead of XML.

In my quest to reclaim my data, I’ve become quite familiar with, and enamoured of json. I know all of the arguments against it, that there are two specs which are in opposition, and that in some edge cases, those collisions lead to poor rendering. All of those arguments pale into insignificance, however, when faced with the simple fact that json is simple, flexible and simple.

As an example, I knocked together a jsonfeed for this blog in about ten minutes, most of which was spent upgrading my Hugo installation. The latest Hugo version has support for output formats, and json is one of the supported formats.

After making a placeholder page for the jsonfeed output, using the necessary frontmatter as per the Hugo documentation, I wrote the following jsonfeed template:

	{
    "version": "https://jsonfeed.org/version/1",
    "title": {{ .Site.Title | jsonify }},
    "home_page_url": {{ .Site.BaseURL | jsonify}},
    "feed_url": {{ .Permalink | jsonify }},
    "icon": "{{ .Site.BaseURL }}icon440.png",
    "favicon": "{{ .Site.BaseURL }}icon72.png",
    {{- if isset .Site.Params "description" }}
    "description": "{{ .Site.Params.description }}",
    {{- end }}
    {{- if isset .Site.Params "author" }}
    "author": { "name": "{{ .Site.Params.author | jsonify }}" },
    {{- end }}
    "items": [
    	{{- range $i, $e := first 10 .Site.Pages }}
        	{{- if $i }}, {{ end }}
        		{
                {{- if isset .Params "title" }}
                	"title": {{ .Title | jsonify }},
                {{- end }}
                    "date_published": {{ .Date.Format "2006-02-01T15:04:05-07:00" | jsonify }},
                {{- if isset .Params "link" }}
                    "_external-link": {{ .Params.link | jsonify }},
                {{- end }}
                	"url": {{ .Permalink | jsonify }},
                    "id": {{ .Permalink | jsonify }},
                    "content_text": {{ .Summary | jsonify }}
				}
		{{- end }}
		]
	}

Few quick notes on that:

1. The icon/favicon elements are as per the jsonfeed spec. I happened to have 440x and 72x versions of my site icon to hand. This could be adjusted to any setting, or even reference in your Hugo site’s config file.
2. The {{- if $i }}, {{ end }} instruction tells the parser to add commas to all items, except the last. Well, what it actually does is not add commas to all items, unless there is another item following. Odd syntax, but it works.
3. When writing if or range commands in your Hugo templates, always try to remember to add the hyphen, as seen in {{- range $i, $e := first 10 .Site.Pages }}. This make the output file much neater, and it particularly noticeable in json, when stray lines consisting of a line-break can break parsers.
4. The {{- if isset .Params "link" }} element is there to ensure that my linkposts contain the link directly in the feed. It should be for parsers to decide whether the reader then goes to the linked page, or to my page.

My json feed can now be seen at /jsonfeed/index.json, and should be coming to an increasingly overcrowded sidebar any day now.

EDIT: 2017-05-23

Of course, I published that before I actually checked that I was creating valid JSON - spoiler alert: I wasn’t. I’ve fixed the code since, putting in commas after the two .png declarations, and wrapping the Post Content in a pipe to jsonify. Apologies to anyone who followed my half-baked template.