eleventy-plugin-webfinger

An Eleventy plugin for generating a Webfinger configuration file.

Usage

First, add the plugin as a development dependency to your project's package.json file:

npm install --save-dev @jgarber/eleventy-plugin-webfinger

Next, add the plugin to your project's Eleventy configuration file (e.g. eleventy.config.js):

import eleventyPluginWebfinger from "@jgarber/eleventy-plugin-webfinger";

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(eleventyPluginWebfinger);
}

With no additional configuration, eleventy-plugin-webfinger will use a global data object named webfinger to populate a template at the permalink /.well-known/webfinger.

// Using a global data file at `_data/webfinger.js`
const subject = "acct:[email protected]";

const aliases = ["https://jgarber.example"];

const links = [
  {
    href: "https://jgarber.example/avatar.png",
    rel: "http://webfinger.net/rel/avatar",
    type: "image/png",
  },
  {
    href: "https://jgarber.example/about",
    rel: "http://webfinger.net/rel/profile-page",
    type: "text/html",
  },
  {
    href: "https://jgarber.example/users/jgarber",
    rel: "self",
    type: "application/activity+json",
  },
];

export default { subject, aliases, links };

If a global data file (or other data file) doesn't suit your needs, you may directly provide configuration to the plugin:

import eleventyPluginWebfinger from "@jgarber/eleventy-plugin-webfinger";

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(eleventyPluginWebfinger, {
    subject: "acct:[email protected]",
    aliases: ["https://jgarber.example"],
    links: [
      {
        href: "https://jgarber.example/avatar.png",
        rel: "http://webfinger.net/rel/avatar",
        type: "image/png",
      },
      {
        href: "https://jgarber.example/about",
        rel: "http://webfinger.net/rel/profile-page",
        type: "text/html",
      },
      {
        href: "https://jgarber.example/users/jgarber",
        rel: "self",
        type: "application/activity+json",
      },
    ],
  });
}

The examples above are fairly rudimentary and not that much different from creating a template in your project's source directory. However, consider the example below which reuses data from a different global data file:

// _data/actor.json
const url = new URL("https://jgarber.example");
const id = new URL("users/jgarber", url);

const icon = {
  mediaType: "image/png",
  type: "Image",
  url: new URL("avatar.png", url),
};

const preferredUsername = "me";

export default { url, id, icon, preferredUsername };

// _data/webfinger.js
import actor from "./actor.js";

const { url, id, icon, preferredUsername } = actor;

export default {
  subject: `${preferredUsername}@${url.hostname}`,
  aliases: [url, id],
  links: [
    {
      href: icon.url,
      rel: "http://webfinger.net/rel/avatar",
      type: icon.mediaType,
    },
    {
      href: new URL("about", url),
      rel: "http://webfinger.net/rel/profile-page",
      type: "text/html",
    },
    {
      href: id,
      rel: "self",
      type: "application/activity+json",
    },
  ],
};

Deployment Considerations

The file generated by this plugin, .well-known/webfinger, doesn't have a file extension and should be served with a content type of application/jrd+json. Consult RFC 7033 for details.

You should configure the following HTTP response headers using your hosting provider's configuration. The following configuration is suitable for a _headers file deployed to Cloudflare Pages:

/.well-known/webfinger
  Access-Control-Allow-Origin: *
  Content-Type: application/jrd+json; charset=UTF-8

Limitations

The ./well-known/webfinger configuration produced by this plugin is a static file and, as such, will not respond differently to queries defined by the Webfinger specification (see section 4.1). This plugin is well-suited for personal websites that represent a single "resource" (e.g. a person [you!], a group [your band!], an organization [your crew!]).

Your hosting provider may support query parameters in _redirects files, so perhaps there's a way to dynamically generate files using this plugin. Give it a try!

Acknowledgments

First and foremost, eleventy-plugin-webfinger wouldn't be possible without Zach Leatherman's incredible work creating Eleventy and his stewardship of its community.

eleventy-plugin-webfinger is written and maintained by Jason Garber.