Copy+Paste Atom Feed Generation

(Back to index)

Three questions:

We'll go down the list.

1. What's an Atom feed?

Atom is like RSS, but newer. Which is to say, it's a dingus that computers can look at and say either "oh hey, new posts!" or "okay, we've seen all of these", and therefore can let a computer-user know if there's new posts or not.

Basically, instead of you refreshing our website to see if there's anything new, your computer does it.

2. Why are we making one by hand?

If you know stuff about RSS and Atom feeds, you know that they are almost always generated by the same programs that generate the rest of the webpages.

And ... that's true in this case, too. That program is a text editor. We aren't using a static site generator, so the idea of automatically generating a syndication feed is a non-starter - we can't do it. And it turns out it's not too hard.

3. How are we doing it?

Step one was reading RFC4287 ("The Atom Syndication Format"). If you've never done this, let us show you how it starts:

1.1. Examples

A brief, single-entry Atom Feed Document:

   <?xml version="1.0" encoding="utf-8"?>
   <feed xmlns="http://www.w3.org/2005/Atom">

     <title>Example Feed</title>
     <link href="http://example.org/"/>
     <updated>2003-12-13T18:30:02Z</updated>
     <author>
       <name>John Doe</name>
     </author>
     <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

     <entry>
       <title>Atom-Powered Robots Run Amok</title>
       <link href="http://example.org/2003/12/13/atom03"/>
       <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <summary>Some text.</summary>
     </entry>

   </feed>

So, step 1: copy+paste that into a file called atom.xml; step 2, figure out what each element is so we can fill it in how we want.

title

The feed needs a name and the feed entries need names, put them here. We're not specifying types so the types are text; we do have to < any less-than signs, though.

link

Apparently the feed part should have one of these with a rel="self" in it that points to the correct source of the feed, and each entry should have one with rel="alternate" pointing at the update. Pretty doable.

updated

This looks like an ISO 8601 datetime string. The RFC says it's compatible with those. And us being on a Unix, we have coreutils, which means we have date, which means we can generate one of those by typing date --iso-8601="seconds". Or date -I"seconds", for short.

author

Literally what it says. We're required to give exactly one name; if we do it on the feed, then we can leave it off for the entries. Unless we know which Packbat wrote that entry, and then we can sign it.

id

...okay this one threw us a lot, but the second example had ones which were like tag:example.org,2003:3 and we eventually managed to track through a web of RFCs to find out that RFC4151 ("The 'tag' URI Scheme") is what we needed. Basically: the id should be a unique IRI, and the tag thing is for humans creating unique URIs (a kind of IRI) without having to coordinate with anyone else, and the human part does seem to be optional. For our purposes, we officially had dibs on packbat.neocities.org at and around the start of 2024, so tag:packbat.neocities.org,2024:UNIQUE should work as long as we pick unique stuff to replace the UNIQUE part.

entry

This contains data for an entry in the feed. Fantastic.

summary

It's a summary. We just gotta write some text.

We also decided to use two more things in ours:

contributor

Like an author, except not the author. I guess Atom assumes everything has one unique first author who's a person? That's ... several brave assumptions. Anyway, we're sticking "the Packbats" here for entries one of us claims (like this one!), because the way our system works, more than one of us is inevitably gonna contribute.

content

Hopefully we understood this correctly, but: if we do <content src="https://packbat.neocities.org/copypaste_atom.html" type="text/html"/>, that should mean "the contents of this entry are an HTML file found here". If we do an update that doesn't have content, or has multiple content, we aren't gonna do this content thing, but for this update, I think the correct content is ... here. You just read it.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">

	<title>Neopackbats: A Web Site</title>
	<link rel="self" href="https://packbat.neocities.org/atom.xml"/>
	<updated>2024-06-12T20:29:57-04:00</updated>
	<author>
		<name>The Packbats</name>
	</author>
	<id>tag:packbat.neocities.org,2024:20240612-atomfeed</id>

	<entry>
		<title xml:lang="en">Atom syndication feed added</title>
		<content src="https://packbat.neocities.org/copypaste_atom.html"
		type="text/html"/>
		<link rel="alternate"
		href="https://packbat.neocities.org/copypaste_atom.html"/>
		<id>tag:packbat.neocities.org,2024:20240612-copypaste_atom</id>
		<updated>2024-06-12T20:29:57-04:00</updated>
		<author>
			<name>Packcat</name>
		</author>
		<contributor>
			<name>The Packbats</name>
		</contributor>
		<summary xml:lang="en">Neopackbats now includes an Atom feed
		for feed catchers to follow - which is interesting, because the
		whole site is hand-coded, and Atom feeds are usually generated
		by site generator code. This page summarizes how we made it
		work.</summary>
	</entry>

</feed>

Back to index.