Enabling two way communication with WordPress and GitHub for Issues

This week, using the magic of open web standards, I was able to write an issue post on my own website, automatically syndicate a copy of it to GitHub, and later automatically receive a reply to the copy on GitHub back to my original post as a comment there. This gives my personal website a means of doing two way communication with GitHub.

This functionality is another in a long line of content types my website is able to support so that I’m able to own my own content, yet still be able to interact with people on other websites and social media services. Given the number of social sites I’ve seen disappear over the years (often taking my content with them), this functionality gives me a tremendously larger amount of control and ownership over my web presence and identity while still allowing me to easily communicate with others.

In this post I wanted to briefly sketch what I’ve done to enable this functionality, so others who are so inclined can follow along to do the same thing.

Setting up WordPress to syndicate to GitHub

I’ll presume as a first step that one has both a GitHub account and a self-hosted WordPress website, though the details will also broadly apply to just about any content management system out there that supports the web standards mentioned.

Register your GitHub account and your website with Bridgy

Ryan Barrett runs a fantastic free open sourced service called Bridgy. To use it you’ll need the microformat rel=​​​“me” links on both your GitHub account and your website’s homepage that point at each other.  GitHub will do most of the work on its side for you simply by adding the URL of your website to the URL field for your GitHub account at https://github.com/settings/profile. Next on your website’s homepage, you’ll want to add a corresponding rel=​​​​​“me” link from your website to your GitHub account.

In my case, I have a simple widget on my homepage with roughly the following link:
<a href="https://github.com/username">GitHub</a>
in which I’ve replaced ‘username’ with my own GitHub username. There are a variety of other ways to add a rel=​​​​​“me” link to your webpage, some of which are documented on the IndieWeb wiki.

Now you can go to Brid.gy and under “Connect your accounts” click on the GitHub button. This will prompt you to sign into GitHub via oAuth if you’re not already logged into the site. If you are already signed in, Brid.gy will check that the rel=​​​​​“me” links on both your site and your GitHub account reciprocally point at each other and allow you to begin using the service to pull replies to your posts on GitHub back to your website.

To allow Brid.gy to publish to GitHub on your behalf (via webmention, which we’ll set up shortly), click on the “Publish” button.

Install the Webmention Plugin

The underlying technology that allows the Bridgy service to both publish on one’s behalf as well as for the replies from GitHub to come back to one’s site is an open web standard known as Webmention. WordPress can quickly and easily support this standard with the simple Webmention plugin that can be downloaded and activated on one’s site without any additional configuration.

For replies coming back from GitHub to one’s site it’s also recommended that one also install and activate the Semantic Linkbacks Plugin which also doesn’t require any configuration. This plugin provides better integration and UI features in the comments section of one’s website.

Install Post Kinds Plugin

The Post Kinds Plugin is somewhat similar to WordPress’s Post Formats core functionality, it just goes the extra mile to support a broader array of post types with the appropriate meta data and semantic markup for interacting with Bridgy, other web parsers, and readers.

Download the plugin, activate it, and in the plugin’s settings page enable the “Issue” kind. For more details on using it, I’ve written about this plugin in relative detail in the past.

Install Bridgy Publish Plugin

One can just as easily install the Bridgy Publish Plugin for WordPress and activate it. This will add a meta box to one’s publishing dashboard that, after a quick configuration of which social media silos one wishes to support, will allow one to click a quick checkbox to automatically syndicate their posts.

Install the Syndication Links Plugin

The Syndication Links plugin is also a quick install and activate process. You can modify the settings to allow a variety of ways to display your syndication links (or not) on your website if you wish.

This plugin will provide the Bridgy Publish Plugin a place to indicate the permalink of where your syndicated content lives on GitHub. The Bridgy service will use this permalink to match up the original content on your website and the copy on GitHub so that when there are replies, it will know which post to send those replies to as comments which will then live on your own website.

Post away

You should now be ready to write your first issue on your website, cross post it to GitHub (a process known in IndieWeb parlance as POSSE), and receive any replies to your GitHub issue as comments back to your own website.

Create a new post.

In the “Kinds” meta box, choose the “Issue” option.

Screen capture of the Kinds meta box with "Issue" option chosen.
Kinds meta box with “Issue” option chosen.

Type in a title for the issue in the “Title” field.

In the “Response Properties” meta box, put the permalink URL of the Github repopository for which you’re creating an issue. The plugin should automatically process the URL and import the repository name and details.

The “Response Properties” meta box.

In the primary editor, type up any details for the issue as you would on GitHub in their comment box. You can include a relatively wide variety of custom symbols and raw html including

and  with code samples which will cross-post and render properly.

In the GitHub meta box, select the GitHub option. You can optionally select other boxes if you’re also syndicating your content to other services as well. See the documentation for Bridgy and the plugin for how to do this.

Screen capture of the Bridgy Publish meta box with GitHub chosen
Bridgy Publish meta box with GitHub chosen.

Optionally set any additional metadata for your post (tags, categories, etc.) as necessary.

Publish your post.

On publication, your issue should be automatically filed to the issue queue of the appropriate GitHub repo and include a link back to your original (if selected). Your post should receive the syndicated permalink of the issue on GitHub and be displayed (depending on your settings) at the bottom of your post.

Syndication Links Plugin will display the location of your syndicated copies at the bottom of your post.

When Bridgy detects future interactions with the copy of your post on GitHub, it will copy them and send them to your original post as a webmention so that they can be displayed as comments there.

An example of a comment sent via webmention from GitHub via Brid.gy. It includes a permalink to the comment as well as a link to the GitHub user’s profile and their avatar.

If you frequently create issues on GitHub like this you might want a slightly faster way of posting. Toward that end, I’ve previously sketched out how to create browser bookmarklets that will allow you one click post creation from a particular GitHub repo to speed things along. Be sure to change the base URL of your website and include the correct bookmarklet type of “issue” in the code.

The Post Kinds plugin will also conveniently provide you with an archive of all your past Issue posts at the URL http://example.com/kind/issue/, where you can replace example.com with your own website. Adding feed/ to the end of that URL provides an RSS feed link as well. Post Kinds will also let you choose the “Reply” option instead of “Issue” to create and own your own replies to GitHub issues while still syndicating them in a similar manner and receive replies back.

Other options

Given the general set up of the variety of IndieWeb-based tools, there are a multitude of other ways one can also accomplish this workflow (both on WordPress as well as with an infinity of other CMSes). The outline I’ve provided here is one of the quickest methods for beginners that will allow a relatively high level of automation and almost no manual work.

One doesn’t necessarily need to use the Post Kinds Plugin, but could manually insert all the requisite HTML into their post editor to accomplish the post side of things via webmention. (One also has the option to manually syndicate the content to GitHub by cutting and pasting it as well.) If doing things manually this way is desired, then one will need to also manually provide a link to the syndicated post on GitHub into their original so that Bridgy can match up the copy and the original to send the replies via webmention.

More details on how to use Bridgy with Github manually in conjunction with WordPress or other CMSes can be found here: https://brid.gy/about#github-issue-comment

Further steps

If you’ve followed many of these broad steps, you’ve given already given yourself an incredibly strong IndieWeb-based WordPress installation. With a minimal amount of small modifications you can also use it to dovetail your website with other social services like Twitter, Facebook, Flickr, Instagram, Google+ and many others. Why not take a quick look around on the IndieWeb wiki to see what other magic you can perform with your website!

I’ve documented many of my experiments, including this one, in a collection of posts for reference.

Help

If you have questions or problems, feel free to comment below or via webmention using your own website. You can also find a broad array of help with these plugins, services, and many other pieces of IndieWeb technology in their online chat rooms.​​​​​​​​

Syndicated copies to:

I wrote in the morning again with one or two small snippets later in the evening. I focused mostly on the topic of rel=”me” for profile equivalence and identity-consolidation with about 1,882 words.

I added a couple of new chapter ideas that will need to be fleshed out as well–I’m surprised I’m still coming up with outline pieces.

Today: 3,115 words
Total: 6,532 words

@Mentions from Twitter to My Website

An outline of how I used Indieweb technology to let Twitter users send @mentions to me on my own website.

You can tweet to my website.

One of my favorite things about the indieweb is how much less time I spend on silo sites like Facebook and Twitter. In particular, one of my favorite things is not only having the ability to receive comments from many of these sites back on the original post on my own site, but to have the ability for people to @mention me from Twitter to my own site.

Yes, you heard that right: if you @mention me in a tweet, I’ll receive it on my own website. And my site will also send me the notification, so I can turn off all the silly and distracting notifications Twitter had been sending me.

Below, I’ll detail how I set it up using WordPress, though the details below can certainly be done using other CMSes and platforms.

rel=“me”

The rel=“me” is put on the link that wraps this Twitter icon in my h-card on my homepage.

On my homepage, using a text widget, I’ve got an h-card with my photo, some basic information about me, and links to various other sites that relate to me and what I’m doing online.

One of these is a link to my Twitter account (see screenshot). On that link I’m using the XFN’s rel=“me” on the link to indicate that this particular link is a profile equivalence of my identity on the web. It essentially says, “this Twitter account is mine and also represents me on the web.”

Here’s a simplified version of what my code looks like:

<a href="https://twitter.com/chrisaldrich" rel=“me">@chrisaldrich</a>

If you prefer to have an invisible link on your site that does the same thing you could alternately use:

<link href="https://twitter.com/twitterhandle" rel=“me">

Similarly Twitter also supports rel=“me”, so all I need to do there is to edit my profile and enter my website www.boffosocko.com into the “website” field and save it. Now my Twitter profile page indicates, this website belongs to this Twitter account. If you look at the source of the page when it’s done, you’ll see the following:

<a class="u-textUserColor" title="http://www.boffosocko.com" href="https://t.co/AbnYvNUOcy" target="_blank" rel="me nofollow noopener">boffosocko.com</a>

Though it’s a bit more complicated than what’s on my site, it’s the rel=“me” that’s the important part for our purposes.

Now there are links on both sites that indicate reciprocally that each is related to the other as versions of me on the internet. The only way they could point at each other this way is because I have some degree of ownership of both pages. I own my own website outright, and I have access to my profile page on Twitter because I have an account there. (Incidentally, Kevin Marks has built a tool for distributed identity verification based on the reciprocal rel=“me” concept.)

Webmention Plugin

Next I downloaded and installed the Webmention plugin for WordPress. From the plugin interface, I just did a quick search, clicked install, then clicked “activate.” It’s really that easy.

It’s easy, but what does it do?

Webmention is an open internet protocol (recommended by the W3C) that allows any website to send and receive the equivalent of @mentions on the internet. Unlike sites like Twitter, Facebook, Medium, Google+, Instagram, etc. these mentions aren’t stuck within their own ecosystems, but actually work across website borders anywhere on the web that supports them.

I use the domain name BoffoSocko as my online identity.

The other small difference with webmention is instead of using one’s username (like @chrisaldrich in my case on Twitter) as a trigger, the trigger becomes the permalink URL you’re mentioning. In my case you can webmention either my domain name http://www.boffosocko.com or any other URL on my site. If you really wanted to, you could target even some of the smallest pieces of content on my website–including individual paragraphs, sentences, or even small sentence fragments–using fragmentions, but that’s something for another time.

Don’t use WordPress?

See if there’s webmention support for your CMS, or ask your CMS provider or community, system administrator, or favorite web developer to add it to your site based on the specification. While it’s nice to support both outgoing and incoming webmentions, for the use we’re outlining here, we only need to support incoming webmentions.

Connect Brid.gy

Sadly, I’ll report that Twitter does not support webmentions (yet?!) otherwise we could probably stop here and everything would work like magic. But they do have an open API right? “But wait a second now…” you say, “I don’t know code. I’m not a developer.”

Worry not, some brilliant engineers have created a bootstrap called Brid.gy that (among many other useful and brilliant things) forces silos like Twitter, Facebook, Google+, Instagram, and Flickr to send webmentions for you until they decide to support them natively. Better, it’s a free service, though you could donate to the ASPCA or EFF in their name to pay it forward.

So swing your way over to http://brid.gy and under “Get started” click on the Twitter logo. Use OAuth to log into Twitter and authorize the app. You’ll be redirected back to Brid.gy which will then ensure that your website and Twitter each have appropriate and requisite rel=“me”s on your links. You can then enable Brid.gy to “listen for responses.”

Now whenever anyone @mentions you (public tweets only) on Twitter, Brid.gy will be watching your account and will automatically format and send a webmention to your website on Twitter’s behalf.

On WordPress your site can send you simple email notifications by changing your settings in the Settings >> Discussion dashboard, typically at http://www.exampl.com/wp-admin/options-discussion.php. One can certainly use other plugins to arrange for different types of notifications as well.

Exotic Webmentions

A bonus step for those who want more control!

In the grand scheme of things webmentions are typically targeted at specific pages or posts on your site. General @mentions on Twitter not related to specific content on your site will usually be sent to your homepage. Over time, this may begin to get a bit overwhelming and may take your page longer to load as a result. An example of this is Kevin Marks’ site which has hundreds and hundreds of webmentions on it. What to do if this isn’t your preference?

In my case, I thought it would be wise to collect all these unspecific or general mentions on a special page on my site. I decided to call it “Mentions” and created a page at http://boffosocko.com/mentions/.

Update

While the code snippet just below should work, as of the 3.3.0 update of the Webmention Plugin, there is now an automatic setting at /wp-admin/options-discussion.php that will allow you to use a dropdown UI box to choose the page on your site to which homepage webmentions will be directed.

Then I inserted a small piece of custom code in the functions.php file of my site’s (child) theme like the following:

// For allowing exotic webmentions on homepages and archive pages

function handle_exotic_webmentions($id, $target) {
// If $id is homepage, reset to mentions page
if ($id == 55669927) {
return 55672667;
}

// do nothing if id is set
if ($id) {
return $id;
}

// return "default" id if plugin can't find a post/page
return 55672667;
}

add_filter("webmention_post_id", "handle_exotic_webmentions", 10, 2);

This simple filter for the WordPress Webmention plugin essentially looks at incoming webmentions and if they’re for a specific page/post, they get sent to that page/post. If they’re sent to either my homepage or aren’t directed to a particular page, then they get redirected to my /mentions/ page.

In my case above, my homepage has an id of 55669927 and my mentions page has an id of 55672667, you should change your numbers to the appropriate ids on your own site when using the code above. (Hint: these id numbers can usually be quickly found by hovering over the “edit” links typically found on such pages and posts and relying on the browser to show where they resolve.)

Tip of the Iceberg

Naturally this is only the tip of the indieweb iceberg. The indieweb movement is MUCH more than just this tiny, but useful, piece of functionality. There’s so much more you can do with not only Webmentions and even Brid.gy functionality. If you’ve come this far and are interested in more of how you can better own your online identity, connect to others, and own your data. Visit the Indieweb.org wiki homepage or try out their getting started page.

If you’re on WordPress, there’s some additional step-by-step instructions: Getting Started on WordPress.

Syndicated copies to: