A rather deep dive into how some of the newer CSS can make this age old pattern even better.

Where’s the holistic AI productivity data?

It’s hard to find anything other than anecdata from individuals telling us how AI has made them individually more productive. If AI really was creating measurable improvements in productivity across entire organisations, wouldn’t we be seeing that data?

[nods]

The Goldilocks customizable select height

Even the new custom <select> capabilities bring headaches, but at least Jake's got height sorted for you.

Bayeux Go!

This is great fun!

Dithering tool

A very handy looking tool that certainly beats a laborious Photoshop process.

A guide to destructuring in JavaScript

Here's one from the Piccalilli archives that you might have missed to wrap up this issue.

P.S. this is a good website from personalsit.es.

Sponsor message

Poetic CSS is a new video and text course. Early bird pricing available July 2026.

Understand CSS as a system with Miriam Suzanne — web developer, teacher, and pioneer of modern CSS — so you can write, review, and maintain web styles with confidence on a timeline and under budget.

Register now

Just like with the WordPress integration, I used Astro's pagination capabilities to build a paginated "feed" of posts, to satisfy the "Basic rendering of my AT protocol posts" part of the core features I outlined at the beginning of this series.

Let's get stuck into that bit first. I created a pages/feed/[...page].astro file and filled it with the following:

---
import { fetchAllATPosts } from '@repo/data/atPosts';

import PageLayout from 'src/layouts/PageLayout.astro';
import Pagination from '@repo/ui/Pagination';
import ATPostsRegion from '@repo/ui/ATPostsRegion';

export async function getStaticPaths({ paginate }) {
  const posts = await fetchAllATPosts();
  return paginate(posts, { pageSize: 20 });
}

const { page } = Astro.props;
---

<PageLayout title="Feed" summary="" socialImage="" allowRobots={true}>
  <ATPostsRegion posts={page.data} />
  <Pagination previous={page.url.prev} next={page.url.next} />
</PageLayout>

I'm getting all the posts with the functionality written in the last article, limiting them to 20 per page and then instructing Astro what pages need building with getStaticPaths().

From there and for each page, I've got a page prop, which just like with the WordPress integration, I'm feeding to the <Pagination> component. I'm also feeding that data to the <ATPostsRegion> which I'll break down next.

The AT posts region

I didn't break down the <PostsRegion> in the WordPress section of this series because it is literally just a list of links, but this one is slightly different, but albeit simple. We are in the early days of this rebuild after all!

---
const { posts } = Astro.props;

import ATPost from '@repo/ui/ATPost';
---

<div class="at-posts-region region">
  <h1 class="visually-hidden">Feed</h1>
  <div class="wrapper flow">
    <p>ℹ️ Posts from my <a href="https://bsky.app/profile/bell.bz">Bluesky profile</a>.</p>
    <ul class="at-posts-region__list" role="list">
      {
        posts.map((post) => (
          <li class="flow">
            <ATPost post={post} />
          </li>
        ))
      }
    </ul>
  </div>
</div>

The main reason I wanted to tackle this region was because of that visually hidden <h1>. First here's the page, at the time of writing.

I didn't want a big ol' heading on this page (at least initially), but I do need a top level heading, for assistive tech users, so my ever-useful CSS utility helps a tonne here.

The rest of this file is pretty self explanatory, so let's dig into the component that renders each post.

---
import {
  formatDate,
  convertATPrototocalURIToBlueskyURL,
} from '@repo/utils/helpers';

import MarkdownText from '@repo/ui/MarkdownText';

const { post } = Astro.props;
---

<div class="at-post flow">
  <MarkdownText content={post.content} className="flow" />
  {
    post.media.length
      ? post.media.map((media) => (
          <>
            {media.type === 'image' && <img src={media.src} alt={media.alt} />}

            {/* Like images, but this is specifically an open graph image */}
            {media.type === 'external' && media.thumb && (
              <p>
                <a href={media.uri}>
                  <img src={media.thumb} alt={media.title} />
                </a>
              </p>
            )}

            {media.type === 'video' && (
              <video width="352" height="198" controls poster={media.thumbnail}>
                <source src={media.playlist} type="application/x-mpegURL" />
              </video>
            )}
          </>
        ))
      : null
  }

  <p class="at-post__meta">
    <time datetime={post.date}>{formatDate(post.date, true)}</time>
  </p>

  <dl class="at-post__stats cluster">
    <dt>Likes</dt>
    <dd>{post.likes}</dd>
    <dt>Reposts</dt>
    <dd>{post.reposts}</dd>
    <dt>Replies</dt>
    <dd>{post.replies}</dd>
  </dl>

  <p class="at-post__original-link">
    <a href={convertATPrototocalURIToBlueskyURL(post.uri)}>Original</a>
  </p>
</div>

The first thing I do here is render the markdown text, generated in the last article, with my existing component. With the easy part done, I swiftly move on to looping over the post.media array and rendering appropriate markdown per embed type.

Following that, the post's date is rendered with the <time> element with like, repost and reply count rightly using a description list (<dl>) element to articulate the data appropriately.

The last part is a link out to Bluesky, which I'll bring in to show you:

/**
 * Converts an AT Protocol URI to a Bluesky Web URL
 * @param {string} atUri - The at:// uri (e.g., at://did:plc.../app.bsky.feed.post/...)
 * @returns {string} The formatted bsky.app URL
 */
export function convertATPrototocalURIToBlueskyURL(uri) {
  // Pattern: at://(DID)/(COLLECTION)/(RKEY)
  const regex = /^at:\/\/(did:[^/]+)\/app\.bsky\.feed\.post\/([^/]+)$/;
  const match = uri.match(regex);

  if (!match) {
    return 'Invalid AT Protocol post URI';
  }

  // Matches are in order because of array destructuring, so we use `_` to capture the un-needed part
  const [_, did, rkey] = match;
  return `https://bsky.app/profile/${did}/post/${rkey}`;
}

The aim of the game with this utility is to first match the parts of an AT protocol URI, then use those parts to return a web URL. Because every record in your Personal Data Server (PDS) has a DID (user ID) and rkey, it's a case of applying those URL parts and Bluesky does the rest. Handy.

Wrapping up

That's it! The AT protocol stuff looks incredibly complicated on the surface, but once you understand how PDS records work, it's a really elegant, straightforward system.

There will be a full AT protocol focused iteration of this website, once I've designed and implemented the new UI, so this stuff serves as a basic basis to build on. Hopefully it'll make the idea of implementing the AT protocol on your website more appealing too.

With AT protocol done, let's move on to my favourite part: the music collection, next.

I could go all in at this point and integrate posts, comments, interactions and comments on blog posts, but I'm not in the business of doing that until I fully understand what I'm doing. Throwing code at the wall to see what sticks is a one way high speed train to technical debt city.

If there ever is a time to experiment, it is on your personal site. I'm just trying to eradicate as much tech debt as possible in this project.

What I'm doing instead is what I outlined in planning, specifically where I worked out each iteration. Here it is as a reminder:

As per that planning, I'm still in iteration one, which means this phase of AT protocol integration is going to be a basic rendering of my AT protocol posts.

I say AT protocol and not Bluesky posts because it's worth remembering that Bluesky is the microblogging app built on the protocol. My data (posts) is outside of that platform, on my Personal Data Server (PDS). Right now, at the time of writing, that PDS is on Bluesky's infrastructure, but I will definitely be moving that to something I own, for sure.

Rendering the posts

In order to do this, I need create a new file in my data package — just like I did for the WordPress posts — and lean into the AT Protocol API, using their official package.

Here's the file in whole. I'll break down the important bits:

import { AtpAgent, RichText } from '@atproto/api';
import { getCache, setCache } from './memoryCache';

const agent = new AtpAgent({
  service: 'https://bsky.social',
});

export async function fetchAllATPosts() {
  const targetHandle = 'bell.bz';
  const cacheKey = 'atPosts';
  const cacheTimeout = 3600; // 3600 seconds is 1 hour
  const cached = getCache(cacheKey);

  if (cached) {
    return cached;
  }

  // Authentication is required
  await agent.login({
    identifier: targetHandle,
    password: process.env.BLUESKY_APP_PASSWORD,
  });

  let allPosts = [];
  let cursor = undefined;

  try {
    while (true) {
      // Fetch this cursor from the feed of items
      const response = await agent.getAuthorFeed({
        actor: targetHandle,
        cursor: cursor,
        limit: 100, // Max limit per cursor

        // For now, I'm just doing root level posts. Maybe as this   evolves I'll bring in replies too.
        filter: 'posts_no_replies',
      });

      // Loop each item but filter out reposts and quote posts
      for (const item of response.data.feed.filter(
        (x) =>
          !(
            x?.reason?.$type === 'app.bsky.feed.defs#reasonRepost' ||
            x.post.embed?.$type === 'app.bsky.embed.record#view' ||
            x.post.embed?.$type === 'app.bsky.embed.recordWithMedia#view'
          )
      )) {
        const post = item.post;
        const parser = new RichText({ text: post.record.text || '' });

        await parser.detectFacets(agent);

        let postMarkdown = '';
        const externalEmbed = post.embed?.external || post.record.embed?.external;

        for (const segment of parser.segments()) {
          if (segment.isLink()) {
            let uri = segment.link?.uri;
            let linkText = segment.text;

            // Check if this link matches the external embed link
            // We compare URIs (or check if the embed exists) to get the full version
            if (
              externalEmbed &&
              (uri?.includes('..') ||
                (externalEmbed && (uri?.includes('…') || uri === externalEmbed.uri)))
            ) {
              uri = externalEmbed.uri;
              linkText = externalEmbed.uri;
            }

            postMarkdown += `[${linkText}](${uri})`;
          } else if (segment.isMention()) {
            postMarkdown += `[${segment.text}](https://bsky.app/profile/${segment.text.replace('@', '')})`;
          } else {
            postMarkdown += segment.text;
          }
        }

        // Create a sensible return object type
        const postData = {
          uri: post.uri,
          cid: post.cid,
          content: postMarkdown,
          date: post.record.createdAt,
          likes: post.likeCount,
          reposts: (post.repostCount || 0) + (post.quoteCount || 0),
          replies: post.replyCount,
          media: [],
        };

        if (post.embed) {
        
          // If there are images, add to the return object
          if (post.embed.$type === 'app.bsky.embed.images#view') {
            postData.media = post.embed.images.map((img) => ({
              type: 'image',
              src: img.fullsize,
              alt: img.alt,
              thumb: img.thumb,
            }));
          }

          // If there are open graph images, surface those
          else if (post.embed.$type === 'app.bsky.embed.external#view') {
            postData.media.push({
              type: 'external',
              uri: post.embed.external.uri,
              title: post.embed.external.title,
              description: post.embed.external.description,
              thumb: post.embed.external.thumb,
            });
          }

          // If there are videos, add to the return object
          else if (post.embed.$type === 'app.bsky.embed.video#view') {
            postData.media.push({
              type: 'video',
              playlist: post.embed.playlist, // HLS stream (.m3u8)
              thumbnail: post.embed.thumbnail,
              cid: post.embed.cid,
            });
          }
        }

        allPosts.push(postData);
      }

      // Set the next cursor and break the loop if we're at the end
      cursor = response.data.cursor;
      if (!cursor) break;
    }

    // Cache so it doesn't take forever to work on this locally
    setCache(cacheKey, allPosts, cacheTimeout);
    return allPosts;
  } catch (error) {
    console.error('Error fetching feed:', error);
  }
}

If you want to copy some code to use yourself, use this block and ignore the blocks in the breakdown.

That’s a lot of code in one block. Let's break it down into chunks.

The breakdown

import { AtpAgent, RichText } from '@atproto/api';
import { getCache, setCache } from './memoryCache';

const agent = new AtpAgent({
  service: 'https://bsky.social',
});

The first thing we do is set up dependencies: the agent (not one of those ones) which interfaces with the protocol for us and rich text capabilities that are used to tidy up content. The memoryCache parts are the same as when I integrated the WordPress content.

const targetHandle = 'bell.bz';
const cacheKey = 'atPosts';
const cacheTimeout = 3600; // 3600 seconds is 1 hour
const cached = getCache(cacheKey);

if (cached) {
  return cached;
}

// Authentication is required
await agent.login({
  identifier: targetHandle,
  password: process.env.BLUESKY_APP_PASSWORD,
});

Here, I'm setting the target handle, the key for our memory cache and how long I want data to be cached for. I opted for an hour because I tend to work in short cycles when coding.

Next up, I attempt to load data from cache first, then check it. If there is data in cache, I can return it and move on. If not, the first thing to do is to get the agent to log in.

For the next part, we're going to be within the while loop.

const response = await agent.getAuthorFeed({
  actor: targetHandle,
  cursor: cursor,
  limit: 100, // Max limit per cursor

  // For now, I'm just doing root level posts. Maybe as this evolves I'll
  // bring in replies too.
  filter: 'posts_no_replies',
});

Notice how I leave comments even for myself? I can look back on this in the future and immediately be up to speed

I have posted a lot on Bluesky so right off the bat, I need to use cursors to paginate over multiple chunks of posts. That's fine, because I'm keeping a track of it with the cursor variable. Eventually that cursor will be null, which in turn will break the while loop. Lovely stuff.

The only other bit to touch on is I'm getting only top level posts, not my replies. I'm not much of a reply guy, but I still don't want out of context posts on the feed because it's just noise.

for (const item of response.data.feed.filter(
  (x) =>
    !(
      x?.reason?.$type === 'app.bsky.feed.defs#reasonRepost' ||
      x.post.embed?.$type === 'app.bsky.embed.record#view' ||
      x.post.embed?.$type === 'app.bsky.embed.recordWithMedia#view'
    )
)) {

The data returned, for each page of data, has a feed array that I can now loop over. I do another pass at filtering here. Each line deals with:

1. Reposts, which are classified as posts and I don't want posts I haven't written showing up in the feed
2. Quote posts, which I don't want to deal with yet
3. Quote posts: same as #2, but with media by the quoter

const post = item.post;
const parser = new RichText({ text: post.record.text || '' });

await parser.detectFacets(agent);

let postMarkdown = '';
const externalEmbed = post.embed?.external || post.record.embed?.external;

for (const segment of parser.segments()) {
  if (segment.isLink()) {
    let uri = segment.link?.uri;
    let linkText = segment.text;

    // Check if this link matches the external embed link
    // We compare URIs (or check if the embed exists) to get the full version
    if (
      externalEmbed &&
      (uri?.includes('..') ||
        (externalEmbed && (uri?.includes('…') || uri === externalEmbed.uri)))
    ) {
      uri = externalEmbed.uri;
      linkText = externalEmbed.uri;
    }

    postMarkdown += `[${linkText}](${uri})`;
  } else if (segment.isMention()) {
    postMarkdown += `[${segment.text}](https://bsky.app/profile/${segment.text.replace('@', '')})`;
  } else {
    postMarkdown += segment.text;
  }
}

The aim of the game at this point is to generate a front-end friendly string of markdown that my existing infrastructure can deal with. In order to do that, I need to break down the post.record.text with the RichText utility, supplied by the @atproto/api package.

I can now loop over each segment of content and determine exactly what it is. For example, I check first to see if there's an externalEmbed — AKA a link — and build a markdown link string accordingly. If it's a mention, I create a nice link to that user's profile and finally if it's neither of those, I append raw text value to the markdown string.

const postData = {
  uri: post.uri,
  cid: post.cid,
  content: postMarkdown,
  date: post.record.createdAt,
  likes: post.likeCount,
  reposts: (post.repostCount || 0) + (post.quoteCount || 0),
  replies: post.replyCount,
  media: [],
};

The most self explaining chunk of code here: I'm creating a nice flat return object structure that matches the front-end components.

if (post.embed) {
  // If there are images, add to the return object
  if (post.embed.$type === 'app.bsky.embed.images#view') {
    postData.media = post.embed.images.map((img) => ({
      type: 'image',
      src: img.fullsize,
      alt: img.alt,
      thumb: img.thumb,
    }));
  }

  // If there are open graph images, surface those
  else if (post.embed.$type === 'app.bsky.embed.external#view') {
    postData.media.push({
      type: 'external',
      uri: post.embed.external.uri,
      title: post.embed.external.title,
      description: post.embed.external.description,
      thumb: post.embed.external.thumb,
    });
  }

  // If there are videos, add to the return object
  else if (post.embed.$type === 'app.bsky.embed.video#view') {
    postData.media.push({
      type: 'video',
      playlist: post.embed.playlist, // HLS stream (.m3u8)
      thumbnail: post.embed.thumbnail,
      cid: post.embed.cid,
    });
  }
}

allPosts.push(postData);

The next time I add something to these checks, I'll refactor this to be a switch statement. For now, I will live my life.

Now, the last bit of data massaging is left for this iteration. I'm checking over a couple of cases to render images or video depending on what embed content I've got to work with. Again, this is all about creating flat (as possible) structures for the front-end components to consume.

After all of that, I push that post into the higher level array, which we'll cache and return.

Wrapping up

That's the data sorted, so the next thing to do is wire it up to the website itself. I'll tackle that in the next one!

We’re approaching—or arguably are in—an era where ‘made by humans’ is a differentiator. A notion that something beyond money and prompts was put into whatever the heck it is we’re using or consuming or enjoying. We should never lose sight of that.

A social filesystem

A very good explainer of how the AT protocol stuff actually works.

I could've rickrolled the entire FIFA World Cup. All I needed was my ID.

Actually mind-blowing read. Never use client-side only auth, pals.

Context-aware headings in HTML

It's about time we got this!

Billy

One for the freelancers/moonlighters amongst us who are sick of over-complicated invoice solutions.

Some practical examples of view transitions to elevate your UI

Here's one from the Piccalilli archives that you might have missed to wrap up this issue.

P.S. this is a good website from personalsit.es.

Sponsor message

FFConf is a room full of people who still give a damn about the web and its community - with talks meant to be experienced, not bookmarked.

Sessions announced, so far: motion in the browser, mad CSS, systems design lessons from a chicken restaurant, and The AI hype, layoffs, a barely-recognisable industry and the search for being human in tech.

Limited early bird tickets available now.

Get your early bird ticket

If you are wondering what 'lexicons' and 'the Atmosphere' are, don't fret. This article will explain what they mean, why you should care about Standard.site, and walk you through exactly how you can implement Standard.site using some simple JavaScript or a plugin for your favourite content management system.

What Standard.site is and why you should care

If Bluesky is the network's answer to short-form microblogging, think of Standard.site as its equivalent for blogs, newsletters, and long-form journalism.

At its core, Standard.site is an open schema that dictates how articles and essays should be formatted as data. When you publish a blog post normally, it lives on your website and relies on scrapers or RSS feeds to be shared. By adopting the Standard.site lexicon, your long-form content becomes a natively understood piece of data on the decentralised web.

One of the most overt benefits we get from defining Standard.site lexicons for our publication are enhanced rich embeds on Bluesky, like this:

We also get many other benefits. For example, I was surprised to see that the professional identity network Sifa ID displayed my posts upon my profile. It was also pleasant to see my posts naturally populate on readers like pckt, Docs.surf, potatonet, and Leaflet without any additional work on my part.

The strength of AT Protocol is that data is interoperable and can be shared, which plays into the strength of Standard.site, which is that a single set of well structured-schemas. The result is that various indexers and tools can all work with the available data in their own ways, knowing how it'll be structured. Your content can be moved between hosts without losing your data or the audience you've built, and there is no single controlling authority. To get further into this, however, we must first establish an understanding of the AT Protocol.

Understanding the AT Protocol

To implement Standard.site, you will want to understand the Authenticated Transfer Protocol (known colloquially as the 'AT Protocol' or 'atproto') at least at a surface level. The AT Protocol is a decentralised system designed to give users ownership of their data.

To explain it at its simplest, you have a Personal Data Server (PDS) which hosts user accounts. Currently, the largest PDS is provided by Bluesky, but anyone can run their own. A PDS holds lots of user accounts, and each user account can hold records, which are data.

Each user account can be identified by a globally unique DID (Decentralised Identifier) that acts as their permanent ID. A DID looks like this: did:plc:7qg6mz2xtzozxkgbcvf4pdnu. Each account also has a handle, which comes in the form of a DNS record. We can see this in that people on Bluesky's PDS who haven't configured a custom domain for their account have a handle like this: bsky.bsky.social. If you navigate to that in a browser, it'll take you to the Bluesky page: https://bsky.bsky.social.

Each account features a data repository that holds collections of JSON records. These JSON records must follow specific structures called lexicons. Lexicons are just schemas, like JSON-Schema or OpenAPI, which define how the JSON must be structured and formatted. Records are put into 'collections', which we can think of as folders. A collection is identified by a Namespace Identifier (NSID) which makes reference to a domain to identify schemas.

Let’s run through an example with Bluesky so we can really get a handle on things. When a user signs up to Bluesky, a self record is created in the app.bsky.actor.profile collection of that user's data repository with information about the account, like its name and profile description. Piccalilli's looks something like this:

{
  "uri": "at://did:plc:lyk2pixxcmyeu4jrapaq26fy/app.bsky.actor.profile/self",
  "cid": "bafyreihzo3igobmunvk6tmsaqgyatyw5gona4kiayvm2f62lymc5dzqjvu",
  "value": {
    "$type": "app.bsky.actor.profile",
    "createdAt": "2024-08-01T12:44:51.324Z",
    "description": "Level up your front-end skills. Stay for the approachable, friendly content and go away with transferable skills you can use day to day.",
    "displayName": "Piccalilli"
  }
}

Then, every time a post is made, or the Piccalilli account likes something, or blocks someone, or does anything else on Bluesky, a new record is created to represent that action. For instance, when Piccalilli reposts something, a new record is created under the app.bsky.feed.repost collection.

Almost everything is a record, inside a collection, under a user account (identified by a DID), on a PDS.

Notably, everything on ATProto is public. There is no concept of private records, which means we can go out and inspect or reference all the data on the protocol. There are a number of tools for inspecting AT Protocol data, but Taproot and PDSLs are my favourites. Search for your account handle, and you'll be greeted by your underlying records. Have a poke around to help wrap your head around the structure and how everything fits together.

The two core records

Now we've (hopefully) got at least (somewhat) of a (fledgeling) understanding of AT Protocol, we can start hooking up Standard.site. To get started with Standard.site, we need to create two specific types of records in your AT Protocol repository:

1. A Publication Record, which defines information about our publication itself.
2. Document Records, which contain information about individual articles themselves.

It is these records that Bluesky and the rest of the Atmosphere will reference. You can create them any one of a number of ways. AT Protocol is very open, and you can create records via a variety of methods, but for the purposes of this article, I'll be showing a JavaScript approach using the official @atproto/api npm package.

You will need to authenticate to create these records. The easiest way to do so is by creating an app password under Privacy and Security in Bluesky's settings. An app password gives access to your account and looks like this: fg2g-xob3-xl78-5ezy.

Publication record

The first step in support is having a publication record adhering to the site.standard.publication lexicon. You only need to create this record once per-publication.

Using the AT Protocol SDK, you can authenticate and create this underlying JSON record for your site with the script below, replacing the template values here with your publication's details.

For the purpose of illustration, this script only sets required properties.

import { AtpAgent } from "@atproto/api";

// Initialise the agent (use your specific PDS if not on Bluesky)
const agent = new AtpAgent({ service: "<https://bsky.social>" });

async function createPublicationRecord() {
  // 1. Authenticate (Always use an App Password, never your main password)
  await agent.login({
    identifier: "your-handle.bsky.social",
    password: "your-app-password",
  });

  const did = agent.session.did;

  // 2. Define the Publication Record
  const publicationRecord = {
    $type: "site.standard.publication",
    url: "<https://example.com>",
    name: "My Awesome Blog",
  };

  // 3. Write the record to your repository
  try {
    const response = await agent.com.atproto.repo.createRecord({
      repo: did,
      collection: "site.standard.publication",
      record: publicationRecord,
    });

    console.log("Publication record created!");
    console.log("Your AT-URI is:", response.data.uri);
  } catch (error) {
    console.error("Failed to create publication:", error);
  }
}

createPublicationRecord();

If this script was successful, it should output a message reading 'Publication record created!', followed by an AT-URI. Save this, because we'll need it later. In the future if we need to amend this record, we can revise the record directly.

Theming

Though the above script is great, we can take it a bit further and add some more pizazz by defining a theme. You can create a theme to lend some more style to how your content displays in readers and how Bluesky embeds it. This is done by adding theming fields to your publication record. You need to specify a background, foreground, accent, and accentForeground. If you're setting any of these values, you must set all of them.

Bluesky uses accent and accentForeground like so:

You should check that your foreground and background and accent and accent foreground all have appropriate contrast. Bluesky previously took these values directly, but now they do some contrast adjustment of their own.

You, unfortunately, cannot change the text which appears on the Bluesky embed button, which will always be 'View Publication' if you publish yourself. Some external Standard.site enabled services have their own special buttons with custom text and icons, but these are hard coded in the Bluesky client.

Verifying your publication

Next, we have the optional step of creating a file at /.well-known/site.standard.publication containing the AT-URL outputted by our record creation script. This verifies that your domain controls your publication record.

Most services, Bluesky included, don't require this verification. Indeed, some hosts might not let you write to the /.well-known path. However, if you can create a file named site.standard.publication within /.well-known and put your AT-URL within it, your publication will be more widely supported. This verification only needs to be done once.

You can check this has been created correctly by going to your URL on your site. For example, for my personal website, I can visit https://vale.rocks/.well-known/site.standard.publication in my browser and see my AT-URI:

at://did:plc:7qg6mz2xtzozxkgbcvf4pdnu/site.standard.publication/3mn2c332ulp2u

Document records

Now that your publication record exists, you need to create per-document records following the site.standard.document lexicon. Every document needs its own record.

Standard.site supports having your document's content in the record, which is the approach that Offprint, pckt, Leaflet, and some other publishing platforms use. Whether you do this is up to you.

If you do include the content, then it can be displayed natively in Standard.site reader applications, and Bluesky embeds will provide a reading time estimate. For the purpose of this script, I'll again only be including required properties.

import { AtpAgent } from "@atproto/api";
const agent = new AtpAgent({ service: "<https://bsky.social>" });

async function publishDocumentRecrd() {
  await agent.login({
    identifier: "your-handle.bsky.social",
    password: "your-app-password",
  });

  const did = agent.session.did;

  // 1. Define the Document Record
  const documentRecord = {
    $type: "site.standard.document",
    site: `at://your-did/site.standard.publication/your-pub-rkey`, // Full AT-URI of your publication
    title: "My New Post",
    publishedAt: "2026-06-11T00:00:00.000Z",
  };

  // 2. Write the record to your repository
  try {
    const response = await agent.com.atproto.repo.createRecord({
      repo: did,
      collection: "site.standard.document",
      record: documentRecord,
    });

    console.log("Success! Document record published to the Atmosphere:");
    console.log(response.data.uri);
  } catch (error) {
    console.error("Failed to publish document:", error);
  }
}

publishDocumentRecord();

If this script was successful, it should output a message reading 'Success! Document record published to the Atmosphere:', followed by an AT-URI. Save this, because we need it to verify the document.

Verifying your document

To complete the two-way verification, the HTML <head> of your live article must contain a link tag pointing back to the document record you just created:

<link rel="site.standard.document" href="at://did:plc:your-did/site.standard.document/the-record-rkey" />

Once these ends are tied together, your webpage and document record point to each other, and clients across the decentralised web can seamlessly reference the record.

Adding images

If you look through the Standard.site docs at all, you might notice references to icons and cover images. To make use of these, we must upload a blob, which is what unstructured data (like images) within a repository are called.

We need to upload the blob first, so that we can refer to it with a reference in our record. Here is an example of uploading an image as a blob and then referencing it to use it as a cover image.

import fs from "fs";
import { AtpAgent } from "@atproto/api";
const agent = new AtpAgent({ service: "<https://bsky.social>" });

async function uploadImageAndPublishDocument() {
  await agent.login({
    identifier: "your-handle.bsky.social",
    password: "your-app-password",
  });

  const did = agent.session.did;

  // 1. Read the local image file into a buffer
  const imageBuffer = fs.readFileSync("./path/to/your/cover.jpg");

  // 2. Upload the blob to your repository
  const { data: blobResponse } = await agent.com.atproto.repo.uploadBlob(
    imageBuffer,
    { encoding: "image/jpeg" }
  );

  console.log("Blob successfully uploaded!");

  // 3. Define the Document Record, attaching the returned blob reference
  const documentRecord = {
    $type: "site.standard.document",
    site: `at://your-did/site.standard.publication/your-pub-rkey`,
    title: "My New Post with a Cover Image",
    publishedAt: "2026-06-18T12:00:00.000Z",
    cover: blobResponse.blob, // This links the blob to your document
  };

  // 4. Write the document record to your repository
  try {
    const response = await agent.com.atproto.repo.createRecord({
      repo: did,
      collection: "site.standard.document",
      record: documentRecord,
    });

    console.log("Document record with cover image published:");
    console.log(response.data.uri);
  } catch (error) {
    console.error("Failed to publish document:", error);
  }
}

uploadImageAndPublishDocument();

Setting up Standard.site on CMS platforms

If writing JavaScript to push records manually sounds tedious, or you're already using a major content management system, you might prefer to have the process handled for you. How you integrate Standard.site depends very much on how your own site is built, and some platforms have ready-made integrations via plugins that handle all of the above behind the scenes:

• WordPress: Has the ATmosphere plugin and the Wireservice plugin.
• CraftCMS: Has a plugin simply called Standard.site.
• Obsidian: Has a community plugin.
• Static sites: Generators like 11ty, Hugo, Astro, and Jekyll can use a dedicated CLI tool called Sequoia.

Checking it works

Obviously, creating all these records and configuring all this Standard.site business is a bit useless if it doesn't actually work. The easiest way to test is by just plopping a link to a post on Bluesky and hoping it embeds, but if it doesn't, it can feel a tad opaque when it comes to figuring out what went wrong.

To rectify this, you can make use of Standard.site Validator by Thomas Karpiniec. Consider returning to Taproot or PDSLs to study and review your records. Both will let you know if anything fails to validate and where things went awry.

Further reading

For some further reading, Piccalilli's own Mat Marquis, creator of the JavaScript for Everyone course, has written his own posts documenting his understanding of and implementation of Standard.site on his own blog.

If you want to have multiple Standard.site publications under a single domain, then Jason Lengstorf has an in-depth guide on the Code.TV blog.