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.

Heydon Pickering has been very busy building out a declarative, web component-based system for making music with HTML, along with a stunning companion site.

Web browsers on video game consoles

A thoroughly fascinating read.

Standard Reader

This is a really nice RSS reader-like standard.site reader.

How building an HTML-first site doubled our users overnight

We challenged Alistair to write this and boy, did they deliver!

An in-depth guide to customising lists with CSS

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

P.S. I wrote a blog post for a change.

Sponsor message

Optimize visitor experience with DebugBear

DebugBear real user monitoring tells you how fast your website is for your visitors and where you need to optimize.

Get in-depth diagnostics across Google’s Core Web Vitals metrics. For example, you can see what page elements and scripts are responsible for slow user interactions.

Learn More

An extremely good and important read.

LLMs and performative productivity

A rather detailed post that links out to some really interesting studies too.

When to use (and not use) CSS shorthand properties

As I see it, margin, padding and border are safe as houses but there is evil out there, such as the flex shorthand.

Being “good” at things

Just a thoroughly delightful read, as per usual from Jim.

The amazing mail sent to a video game publisher

An interesting look behind the curtain that will make you smile.

My favourite 3 lines of CSS

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

P.S. wanna see a glow up?.

Sponsor message

How fast is your website?

The free DebugBear website speed test provides an in-depth technical report on your page speed. You can also see how your Core Web Vitals have changed over time, based on Google’s Chrome User Experience Report.

Test Your Website Speed

Incredibly addictive game. Best to use a mouse/trackpad than a touch device to give yourself a chance too!

Dollar Slice Surf Report, New York City

A cool project by Scott Jehl as, using pen, pencil, Procreate and Figma as a much needed antidote to the slop era.

Speaker feeds

FFconf have a huge library of previous talks and speakers. Now, you can discover their RSS feeds and follow them. Handy!

Let's get creative

Folks love it when we share indexes of cool stuff, so here's another!

Protecting Blue Corridors

Some absolutely delightful design and data visualisation work here.

Styling Tables the Modern CSS Way

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

Identify and fix web performance issues with DebugBear.

Is your website slower than it should be? DebugBear provides in-depth web performance insights based on synthetic tests and real user monitoring.

Detect pages with critical issues, get in-depth technical reports to identify solutions, and measure how performance impacts conversion rates.

Start Optimizing Your Website

All that said, for the purposes of this article, I’m a front-end web developer who has spent their 7 year career building a product for testing accessibility of mobile apps. I’d like to give you — a front-end web developer, who may not have mobile experience — a quick run-through to the mobile apps built with web technologies landscape.

What is a hybrid mobile app?

As a front-end web developer, we’re used to our HTML content being rendered in the browser whether it’s being generated by a framework like React or Vue, or being served from an HTML file.

The mobile app world is a quite different story where the rendered content doesn’t follow agreed upon and maintained guidance, like web standards. For example, Apple and Google completely govern their own native tech stacks for building iOS and Android apps respectively. Those tech stacks create elements on the screen called Views. Then there’s the 3rd party cross-platform frameworks such as React Native, .NET MAUI (previously Xamarin), Flutter. These all allow you to build both an Android and iOS app, and sometimes a web and/or desktop app, from a single code base, but they each do that process a bit differently to each other.

React Native and .NET MAUI generate Views that mimic or are very similar to native mobile Views. They are designed to use technologies familiar to React and .NET developers: TypeScript/JavaScript with CSS and C# with XAML. Flutter is in it’s own league because it uses Dart to build Widgets that are rendered by it’s own graphics engine, bypassing the concept of native Views entirely.

While all these frameworks are often referred to in discussions of hybrid mobile apps, I prefer to distinguish them as cross-platform or code-once frameworks and reserve hybrid to specifically describe the subset of apps which present a blend of web and mobile content.

We’ll define a hybrid mobile app as follows: “A mobile app which primarily features HTML content rendered in WebViews alongside some native mobile content or functionality”

A WebView is a native mobile View which acts as an embedded web browser component to render HTML content inside of it instead of native controls like sliders or buttons. The mobile browser apps such as Safari and Chrome utilize a WebView as the main component with the addition of peripherals like the URL bar and back button. That’s a route to web developers to feel empowered rather than hindered.

The cross-platform framework names I haven’t mentioned yet are by this definition, hybrid app development frameworks: Ionic, Capacitor, Cordova/PhoneGap. It’s a bit complicated to untangle what each framework is and does, so we’ll dive into that in the next section.

Hybrid App Development Frameworks

Let’s start by talking about Apache Cordova/Adobe PhoneGap, since it’s the original hybrid framework, created back in 2009. Here’s the overview statement on the Cordova documentation site:

Apache Cordova is an open-source mobile development framework. It allows you to use standard web technologies - HTML5, CSS3, and JavaScript for cross-platform development. Applications execute within wrappers targeted to each platform, and rely on standards-compliant API bindings to access each device's capabilities such as sensors, data, network status, etc.

There’s some history with the project being acquired by Adobe, including in an offering called PhoneGap, but that was discontinued in 2020. Cordova is still alive and actively maintained, but you may see references to PhoneGap while looking for hybrid app development topics.

Cordova isn’t a UI framework, but rather a runtime environment for your web app on a mobile device. This means you could take an existing web app that you built with your favorite front-end tools and package it up to render inside a WebView in both an iOS and Android app. Now there’s quite a lot of reasons why you wouldn’t want to to that, but let’s cover the other runtime frameworks first.

Capacitor is a newer option for a hybrid framework to ship your web content wrapped in a mobile app, developed in 2018 as a modern alternative to Cordova/PhoneGap. The intro on the Capacitor docs site reads:

Capacitor is a cross-platform native runtime that makes it easy to build performant mobile applications that run natively on iOS, Android, and more using modern web tooling. Representing the next evolution of Hybrid apps, Capacitor creates Web Native apps, providing a modern native container approach for teams who want to build web-first without sacrificing full access to native SDKs when they need it.

What separates Capacitor from Cordova is that it’s built and maintained by the Ionic framework team. While the former are both native runtime frameworks, Ionic is actually a front-end UI framework for hybrid apps. Ionic can be used with both Cordova and Capacitor, but Capacitor is designed specifically to work in conjunction with Ionic. Here’s the introduction on the Ionic docs site:

Ionic is an open source UI toolkit for building performant, high-quality mobile apps using web technologies — HTML, CSS, and JavaScript — with integrations for popular frameworks like Angular, React, and Vue.

Now we’re finally in the front-end developer’s domain! Before we dig into it too much, let’s go over some important design concepts for hybrid apps.

Designing a Hybrid App

Like I said earlier, you can use either Capacitor or Cordova, to wrap your existing web front-end into a WebView inside a mobile app, but there are some considerations to make since content built for the web is structured quite differently than content built for mobile.

For example, a common pattern in web apps is a single page with lot of content that can be scrolled to or jumped to with links/landmarks. Whereas, in a mobile app, content is often better presented in small chunks with navigation through a flow of multiple screens. Mobile app user experience is built around the fact that the content is displayed in a small viewport, but the web was originally built for desktop and adapted to suite mobile devices as their browser became more and more capable.

I’ve spoke with folks in the industry that claim most users can’t tell whether an app is presenting native content or a WebView, but I find that hard to believe. Maybe I’m biased because I know too much about both, but it says a lot if a user downloads your app instead of visiting your website since there’s a much higher barrier to entry. They likely took the extra effort to open the App Store or Play Store and remember or find their account password to install your app because they want a native mobile experience. One thing I can confidently say is that a screen reader user will definitely know the difference since it will literally announce WebView when they hit one, and the landmarks are different, like the fact that Android only has 1 level of heading compared to the 6 levels in HTML <h1>-<h6>.

So all that said, how do you build a stellar hybrid app user experience? By using the concepts of responsive and mobile-first web design of course!

Figma has a wonderful article which covers the topic focusing on websites, but can be applied to hybrid apps as well:

“Mobile-first website design flips the traditional Web development approach. Instead of starting with a desktop layout and scaling down, you begin with a mobile website design. This approach prioritizes smaller screens, slower Internet connections, and the needs of on-the-go users.”

Another layer to mobile-first design is that Android and iOS each have a look and feel uniquely branded to Google and Apple. We’ve established that the web and mobile ecosystems are very different, but iOS and Android are almost just as different too. So you’re faced with some choices: design 2 experiences, pick iOS or Android and ship it to the other platform anyways, or roll your own that ideally caters to both. Trust me, I’ve seen it all, and my least favorite is an Android styled app shipped to iOS

While companies/brands love the idea of a consistent experience across platforms, users prefer your app to look behave like the rest on their device do. A lot of factors go into choosing a design pattern for an app such as target audience, development resource capacity, etc, so let’s set that aside and finally dig into building the bits

Building a Hybrid app Front-end

I want to bring us back to Ionic because its UI component library allowing front-end developers to build seamless experiences for both iOS and Android from a single codebase using technologies you know and love. It’s full of mobile-first components which render on iOS matching Apple’s aesthetics and on Android matching Material Design, Google’s open-source design system. These components are available in Angular, React, Vue, and plain ole JavaScript with beautiful interactive demos on the documentation site.

Let’s take a closer look at a Toggle component which is commonly used in the settings of a mobile app. In React, you import the IonToggle from Ionic’s library and use it just like you would any component for a web-first app.

import React from 'react';
import { IonToggle } from '@ionic/react';

function Example() {
  return (
    <>
      <IonToggle>Default Toggle</IonToggle>
      <IonToggle checked={true}>Checked Toggle</IonToggle>
      <IonToggle disabled={true}>Disabled Toggle</IonToggle>
      <IonToggle checked={true} disabled={true}>
        Disabled Checked Toggle
      </IonToggle>
    </>
  );
}
export default Example;

On iOS, you’ll get 4 toggles in Apple’s well known style.

For Android, the recognisable material design elements are used.

All of the Ionic components can be styled with CSS custom properties and standard CSS, so you can achieve that consistent experience across platforms by modifying the iOS and Android styles slightly or make them match exactly.

Accessibility

As digital accessibility advocate, I can’t write an article without touching on the topic. I think of accessibility in 2 realms: compliance and user experience.

The realm of compliance focuses on building digital content that adheres to the Web Content Accessibility Guidelines (WCAG). These are the guidelines which legislature around the world reference, and large enterprises strive to meet. There isn’t a similar de facto standard for mobile app accessibility despite the immense difference in how content is rendered, but instead, there’s only adaptations and interpretations of WCAG for mobile.

On the other hand, Apple and Google put emphasis on accessibility through the user experience of the iOS and Android ecosystems. There’s Apple’s Human Interface Guidelines with a foundations section dedicated to accessibility, and the Android Developer guide on accessibility.

There’s no straightforward way to make a perfectly accessible app today, but that’s ok! Just as with most things in life, it’s about finding the right balance. On the compliance side, that WebView inside a mobile app is rendering HTML, so WCAG criteria can be directly applied, so there’s certainly advantages for hybrid apps in that regard. However, accessibility compliance doesn’t always equate to a high quality user experience, which is where the advice from Apple and Google come into play.

Wrapping up

While the world of mobile apps can be intimidating to a front-end web developer, it’s certainly worth exploring, even to be aware of the landscape for if you find yourself in a project in the future.

With that in mind, I hope this article is a useful introduction and shows that you don’t have to step completely out of your comfort zone thanks to the concept of hybrid mobile apps, providing a very familiar experience. It makes them a useful jumping off point!