This is a quick getting started guide for Yarns Microsub Server. This post will be updated and expanded.

Yarns is a Microsub server that runs on your WordPress site. This means it can help you follow feeds from blogs, websites, and social media all in place, running on your own server.

You tell Yarns which feeds you want to follow, and it will collect new posts in the background. It can understand feeds in several different formats (Microformats, RSS, Atom, JSONFeed).

Rather than viewing posts in Yarns itself, you can view and interact with your timeline a Microsub client, such as Indigenous, Monocle, Together or others.

If your site supports Micropub, then you can respond to your timeline in any of those client apps, and your responses will be posted on your own website. See below for more details about this.

Accompanied by other plugins that support IndieWeb standards, Yarns can help use your personal website as the centre of your online identity.

Installation

Requirements

Yarns is part of the IndieWeb ecosystem, and requires a few parts to get things working.

The easiest way to get started is to install the IndieWeb plugin, with the following extensions:

  • IndieAuth: To log into a Microsub client.
  • Micropub: (optional) To post to your site from a Microsub client.
  • IndieWeb Post Kinds: (optional) To be able to post likes, replies, and other types of responses to your feeds.
    ** Note, if you have IndieWeb Post Kinds installed, you’ll need to upgrade to at least version 3.3.1 for Yarns to work.

How to install

To install Yarns, download the latest release from its Github repository.

Then install in WordPress by going to Plugins->Add New->Upload Plugin, and selecting the .zip you just downloaded.

Finally, click ‘activate’ when prompted.

First steps

Once you’ve installed Yarns, a page called “Yarns Microsub Server” will be accessible in your WordPress dashboard.

If you have the IndieWeb plugin installed, this page is linked under the “IndieWeb” menu.

If you don’t have the IndieWeb plugin installed, this page can be found in the “Settings” menu.

Either way, navigate to “Yarns Microsub Server”, and you’ll see something like this:

Creating channels

When you subscribe to feeds in Yarns, they are organized into channels. For example, I keep have channels for News, Sports, IndieWeb, and others.

So the first thing you’ll want to do is create a new channel in which you can start to follow some feeds.

To do so, complete the section labelled “Add a new channel” from the “Yarns Microsub Server” page in your WordPress dashboard:

Find the "Add a new channel" heading, enter a channel name, and click "+ Add channel"

You can name a channel whatever you like, and you can change the name later.

Tip: If you want to be fancy, I recommend adding emojis as icons (e.g. “📰 News”).  You can copy and paste emojis from a site like emojipedia.

Following feeds

Once you’ve created a channel, you can follow feeds inside it. First, click on the channel name from the Yarns page in your WordPress dashboard:

You’ll see an option to “Follow a new site.” Enter the address for a website you want to follow, click ‘Search,’ and Yarns will attempt to find feeds it can follow.

If it finds feeds on that website, Yarns will display them as a list.

Some sites (like mine) have a lot of feeds. To help you choose which feed to subscribe to, you can click ‘preview’ and Yarns will show you a quick snapshot of the most recent posts in that feed.

When you’re ready, click ‘Subscribe’ and the feed will be added to this channel.

From now on, Yarns will regularly check to see if there are new posts from this feed. If so, they’ll be saved for you to view at your convenience.

** Note: Some Microsub clients, like Together, will let you manage channels and feeds within the client.

Feed items are only stored temporarily

Items from your feeds, such as articles, notes, or other types of posts, are saved in a database on your own site.

Feed items are only stored for a limited time (14 days by default). And, when you first add a feed, it’s contents will only be added if they were published within that time limit.  If you want to edit the storage period, you can do so under “Yarns options”:

** Technical note: Yarns’ feed items are currently stored as a custom post type in the WP_Posts table of your WordPress site. There are plans to change this, as noted on Yarns’ GitHub.

Viewing feeds

To view your feeds, you’ll need to use a Microsub client such as

These clients require you to log in using IndieAuth. On WordPress, the easiest way to do this is by adding the IndieAuth plugin.

Once you have IndieAuth working, you can use any of the clients linked above to view your feeds.  Simply log into a client using your website’s domain name, and you’ll see your channel(s) and items from the feeds you added.

For example, here is how my feeds are displayed using Monocle:

Replying to feeds

Microsub clients typically allow you to respond to feed items, just like you might do on timelines in Facebook, Twitter, or other social media platforms.

This is as easy as clicking the response options provided by the client. This sends instructions to your site to create a post.

If you want this feature to work, you’ll need to install the Micropub plugin.  This is because Microsub clients use the Micropub protocol to instruct your site to make a new post.

Additionally, I recommend using the Post Kinds plugin, which makes it easy to define posts as replies, likes, reposts etc.

Customizing channels

Channel order

You can change the order of your channels by dragging-and-dropping them:

 

Channel settings

To access settings for each channel, navigate to that channel, then click “Channel settings”:

Yarns will display something like the following:

Rename a channel

To rename a channel, simply edit its “Name” field and click save.

Delete a channel

If you want to delete the channel altogether, click ‘Delete channel’ from its settings page.

Filter feed items by post type

You can control what kinds of posts will be saved to each channel. For example, if the sites you follow post a lot of post types which don’t interest you, then you can uncheck those types here.

Following social media platforms

You can even use Yarns to follow your timelines from sites like Twitter. The easiest way to do this is with a service like Granary. Neil Mather has posted a nice guide about this.

Debug options

There are a few debug options available in Yarns. Ideally you shouldn’t need these, but you can enable them by checking the “Show debug options” box:

Debug log

The debug log is a record of recent requests/responses between your Microsub client and Yarns’ API endpoint.  I use this for troubleshooting. If you find any bugs with Yarns, you might find it useful to report an issue to Yarns’ Github, including a copy of your debug log.

 

Delete all posts

This button will delete all posts (feed items) in your Yarns channels.

Force poll

This button will poll all channels for new posts, bypassing Yarns’ polling schedule.  This can take some time to complete, so please be patient!

I just changed the look of my website, and I’m pretty happy with the results.  The site still runs on WordPress, and I built a child theme from Matthias Pfefferle’s SemPress theme.

One of my main goals was to make my site a bit more fun and expressive, which I’ve accomplished in a few ways:

1. The new header uses ASCII art wrapped in an SVG.  Because ASCII art is just text, it’s a bit challenging to make it responsive. Putting the heading inside an SVG allows me to fluidly resize it for different screen sizes. This ends up being a nice hybrid of old and new — ASCII art was an early method of representing graphics on computers, and SVG’s popularity on the web is much more recent. The ASCII art itself was generated by patorjk.com’s ascii-art generator.

2. Continuing the theme of old and new, the navigation menu uses the Meyrin font, which was created to resemble the terminal font in the Line Mode Browser — the first popular web browser.  More about the font here and it’s worth checking out its use in CERN’s browser-based emulation of the Line Mode Browser

3. The background image for my site is a photo I took at Nanzen-ji temple in Kyoto.

Still a few bugs to work out (e.g. the header doesn’t display quite right in Safari or on Apple mobile devices), but I’m happy with the new look.

Thank you to @RyersonResearch and especially @joyceemsmith  for inviting me to talk about my research today.  I had a great time talking IndieWeb, and specifically, Bridgy.

Jan 30, 2019 Lunch and Learn at Ryerson Journalism Research Centre

I presented a study I’ve been working on about Bridgy, in which I investigated the challenges arising from its use of Facebook’s API from 2014-2018. IndieWeb’s practice of syndicating to and from silos while also acting as an alternative to the ‘corporate web’ demonstrates simultaneous antagonism and dependence upon corporate platforms. My question then, is how this relationship might complicate IndieWeb’s efforts to build a Web that reflects its principles

I studied Bridgy by sifting through issues on its GitHub repo, identifying recurring challenges and how they were addressed. Additionally, Bridgy’s creator Ryan Barrett was kind enough to talk with with me about his work,  which added context and helped me verify that I was on the right track.

I highlighted three recurring challenges in Bridgy’s development:

1. Mapping between the open Web, where resources are identified using URLs, and platform APIs, where they are are identified using arbitrary IDs. This problem kept recurring, which highlights the ongoing labour necessary to maintain a software like Bridgy.

2. Instances where Bridgy had difficulty determining the privacy status of posts or photos.  These are thankfully uncommon, but present a significant problem when they do occur. Bridgy errs on the side of preserving privacy, but this has sometimes meant compromising its expected functionality.

3. Precarity of relying on APIs. For the most part, Bridgy is able to endure API updates due to ongoing maintenance work by its developers. However, Bridgy lost support for Facebook in 2018, when the API was updated with dramatic privacy restrictions.  These restrictions are a response to Cambridge Analytica’s mass collection of Facebook data, but also impact legitimate apps like Bridgy (and Internet researchers). Fortunately, Bridgy still works with other platforms— e.g. The post you’re reading now was syndicated to Twitter with Bridgy.

The Cambridge Analytica news broke when I was in the middle of studying how Bridgy used Facebook’s API during the same timeline. Being immersed in Facebook’s API helped me understand some of the nitty gritty of what had happened and how this affected third-party developers, and I tried to convey some of that in my talk.

Finally, I think Bridgy’s development history demonstrates the kinds of challenges that arise when trying to build alternatives alongside corporate platforms, instead of simply opting out. While principled technologists attempt to build a Web for the future, they must work through the present. This means contending with messiness, heterogeneity, and resistance from established infrastructures.

Slowly but surely I’ve been chipping away at Yarns Microsub Server, and it seems to working quite well these days.  Therefore, I’ve posted a beta release, which you can download right now.

About Yarns

Yarns is a Microsub Server plugin for WordPress.  This means you can use it to follow blogs and other sites across the web, then view feeds of your subscriptions in a Microsub Client. Then, as long as you’ve set up your website correctly, you can reply to items in your feeds and your responses will be posted to your personal website.

Instructions

For installation instructions, check out the Readme on Yarns’ github repo.

For more info, see an overview of Microsub on IndieWeb.org.

Notes

The biggest challenge of this project has been parsing. Yarns can aggregate posts from websites that are marked up with microformats 2. This is a little like subscribing to an RSS feed, but allows for a more complex variety of post types including likes, replies, events, notes, articles.  Initially, I was writing the parsing functions myself, but was delighted when David Shanske offered to build a library using some parsing functions he had already written for another plugin. Now, Yarns uses David’s excellent Parse This library.  As well as contributing this library, David has made code contributions to Yarns itself and helped me think through several challenges, and I’m grateful for this help!

Since each website can be different, there are still some parsing bugs to be addressed.  If you notice any feeds that are parsed with missing information or other problems, please let me know.

 

I’ve been slowly making some improvements to my Yarns Indie Reader for WordPress, and also seeing very impressive development of other IndieWeb readers such as Together, Indigenous, and Monocle.  These three readers all rely on Microsub, which splits the work of building a reader into two parts:

  • A Microsub server
  • A Microsub client

Together, Indigenous, and Monocle are all clients, which means they don’t have to do the work of managing feeds themselves.  Instead, they connect to a Microsub server (such as Aperture), which does all the work of polling for new posts and fitting content from many different sites with varying formats into one standard structure.

When I started building Yarns, I didn’t know about Microsub, and so I built a reader that performs both tasks. On the one hand, this meant additional work for me, and Yarns is a bit rough around the edges as a result. On the other hand, Yarns is easy to use and functional, and I use it every day.

Upon comparing Yarns to these Microsub-powered readers, I’m trying to sort out its advantages and disadvantages. Now that I know about Microsub, should I Should I continue in the direction I’m going? Should I shift gears? Should I focus my attention elsewhere?

Yarns

  • (Pro) Relatively easy to install because it’s a WordPress plugin.  (Albeit, only available on GitHub at present. I believe my next focus should be releasing on the WordPress plugin repository)
  • (Pro) Low reliance on other components. Yarns works best alongside Webmention, Post Kinds, and an IndieWeb-friendly theme, but can also function more or less standalone. (i.e. Yarns could be useful even for those who haven’t implemented other IndieWeb tools)
  • (Pro) Hosted on your own instance of WordPress. No reliance on third-party servers. This means no third party has a list of what websites you are reading, nor any possibility for control of the your feed.  In practice, existing Microsub servers are trustworthy and built by people whose values I agree with. However hosting your feed yourself promises a greater degree of ownership of your data.
  • (Con) Only works with WordPress.
  • (Con) Yarns currently lacks polish and has a limited feature set (no filtering by channel, no automatically marking posts as read, no multiple accounts).

Microsub readers

  • (Pro) These readers look and function great, and continue to improve.
  • (Pro) Work with any Website that supports Micropub.
  • (Con) Requires Micropub to post. Appeal toward people who have already set up an IndieWeb-style site, or are willing to do so; slightly higher barrier to entry than
  • (Con) There are a few options for Microsub servers, but all are in early development. There is no obvious way to sign up for any Microsub server that I’m aware of. Instead, the most obvious path is to download a microsub server’s code from GitHub and set it up on your own server. This clearly limits Microsub to technically skilled users.  This is not a permanent state of affairs, and is only a problem because Microsub is so young.  Note: This is a *very* temporary limitation, since a public release of aperture is apparently ‘very close’.

Future directions

For my use-case, Yarns is sufficient, although there are many things I’d like to improve. However, the new batch of IndieWeb readers are all excellent, and so may scratch my itch in their own way.  To figure out my next steps, I’ll probably have to wait and see what happens at IndieWeb Summit next week. Nonetheless, I think there are four basic directions I could take:

  1. Continue development of Yarns as a standalone reader.
    • This would be a somewhat rough fit with the emerging IndieWeb ecosystem, but It would provide for some more plurality and diversity of options.
  2. Focus on Yarns as a WordPress hosted Microsub client.
    • This would involve rewriting Yarns to pull from a Microsub server.
    • This is feasible, but would lead to me focusing on front-end design, which isn’t my strong point.
  3. Focus on Yarns as a WordPress hosted Microsub server.
    • Pro: Individuals could easily own their feed server as a WordPress plugin instead of relying on a third-party.
    • Pro: Yarns already accomplishes many of the difficult parts of feed aggregation, and the Microsub spec provides solid guidelines for the rest.
    • Con: This is still a fairly difficult project (at least for me), so I need to figure out if it would be worth the time.
  4. Abandon Yarns altogether and just start using existing Microsub readers.
    • This would free up some time to work on some other projects, such as contributing to existing IndieWeb projects and working on WordPress themes.

I’m still thinking through these options, and leaning toward investigating #3

 

 

Over the past little while I’ve been chipping away at an Indie Reader plugin for WordPress.

It’s still a bit rough at this point, but works well enough that I’m happy to announce it here.

Yarns Indie Reader allows you to subscribe to websites that publish either rss or h-feed. As well as keeping up with your subscriptions, you can like and reply and it create posts on your blog automatically.

Likes and replies made using Yarns are marked up with microformats. So if you have Webmentions enabled on your blog (e.g. using the Webmention plugin), your responses should show up correctly when replying to sites that can receive Webmentions.

 

Yarns Indie Reader screenshot
Screenshot of the Yarns Indie Reader feed

Installing Yarns Indie Reader

Yarns can be installed to your WordPress blog like any other plugin.

Because it’s still a bit rough, I haven’t uploaded Yarns to WordPress’s plugin repository yet.  So to install it you’ll need to download from Github and then upload it manually.

Download: github.com/jackjamieson2/yarns-indie-reader

Getting started

Once you’ve installed Yarns, you’ll need to create a page to view the feed and manage your subscriptions. You can do this by creating a new page with the content [[yarns_indie_reader]]

This is a shortcode that tells the plugin, display the reader here. When you view the page you created, you should see something like this…

Yarns Indie Reader menu
Yarns Indie Reader menu

You won’t see any posts until you add a subscription.  To do so, click on Manage subscriptions. You will see a brief form titled Add a subscription.

  1. Type a URL where it says “Enter a website address…”
  2. Click find feeds
  3. Yarns will check the website you entered and then display a list of its feeds.
  4. Select the feed you want to subscribe to and then click Submit.

Once you’ve subscribed to a site, Yarns will check it every hour or so for new posts. If you’re impatient, click Update feed to check right away.

To view posts from your subscriptions, click View feed.

Likes and replies

Just like most social media sites, you can click respond to posts by clicking ‘like’ or ‘reply’.

Examples of likes and replies created using Yarns:

Integration with IndieWeb

This is my effort to contribute to the IndieWeb. So I’ve tried to support features from other IndieWeb plugins.

Webmention and microformats: Likes and replies made using Yarns are marked up with microformats. So if you have Webmentions enabled on your blog (e.g. using the Webmention plugin), your responses should show up correctly when replying to sites that can receive Webmentions.

Post Kinds. If you’ve installed the Post Kinds plugin, then replies and likes will have post kinds assigned.

Acknowledgements

The foundation of this plugin was adapted from Ashton McAllan’s excellent WhisperFollow plugin.

Parts of the design were inspired by Kyle Mahan’s WoodWind.

Future plans

(in no particular order)

  • When displaying h-feed subscriptions, only h-entry posts are formatted correctly. h-events will be captured but their display is clumsy.
    • To do: Improve display of h-events, add RSVP reply-actions.
    • To do: Add support for other types of posts.
  • Better parsing of post types, probably using the post type discovery algorithm.
  • Improve the layout of the feed on mobile devices.
  • Add better support for h-cards (such as displaying author photos)
  • Add support for websub.
  • Debating whether or not to add auto-scroll for pagination.
  • Add an interactive tutorial or clearer documentation to make the plugin more accessible.
  • Add an option to automatically clear old feed items (currently the database will just get bigger and bigger as more posts are added)
  • Ability to view feed from a specific website.
  • Ability to sort feeds into lists (similar to Twitter’s list feature)
  • My big hope is to be able to subscribe to Twitter, Facebook, or other platform feeds.

 

 

A good read about Facebook from Brian Bergstein at MIT Technology Review: We Need More Alternatives to Facebook – MIT Technology Review

Bergstein compares Facebook’s concentration of power to that of the U.S. television industry in the 60s. He quotes a speech given in 1961 by FCC chairman Newton Minow, which told TV executives:

Your industry possesses the most powerful voice in America. It has an inescapable duty to make that voice ring with intelligence and with leadership. In a few years, this exciting industry has grown from a novelty to an instrument of overwhelming impact on the American people. It should be making ready for the kind of leadership that newspapers and magazines assumed years ago, to make our people aware of their world.

Facebook is in a similar position. And Bergstein argues that the problem now is the same as the problem Minow identified with the television industry — a “concentration of power.”

While Mark Zuckerberg has acknowledged that Facebook must learn and improve in order to “make a global community that works for everyone” I agree with Bergstein that the solution is not likely to be more Facebook. Zuckerberg’s proposals to tweak Facebook’s news feed algorithms to discourage hoaxes and to encourage higher quality content address some problems.  But it still troubles me that any one company could have so much power over the spread of information.

What happened with television, and what Bergstein proposes to address concentration of power online, is the creation of alternatives. The obvious challenge for those who would create alternatives to Facebook is how to address its overwhelming market share. I’m not sure that any single alternative can make a significant dent.  Toward the end of his essay, Bergstein writes:

But having many more niche alternatives to Facebook could be exactly what we need. Even if none stole a significant chunk of Facebook’s users, it might be enough to remind people that even as Facebook becomes more powerful than ever—rolling up massive profits and preparing to beam down Internet access to offline corners of the globe—other options are possible, and vital.

Certainly, it’s difficult for me to imagine another platform that connects me to the same number of friends and colleagues. But I can imagine connecting to those people through a multitude of other means alongside Facebook. And I can imagine that this could encourage myself (and others) to be moderate in our reliance on any single platform.