Getting started
This page covers the two models the SDK is built on: how the AT Protocol handles identity and data storage, and how SkyScribe organises content on top of it.
A Publication is a site.standard.publication record and a Document is a site.standard.document record, the same names the site.standard spec uses. The SDK's types are StandardPublication and StandardDocument.
Categories are a SkyScribe concept, not part of the spec. SkyScribe extends the Publication record with them so authors can group their Documents and put them in the order they want shown, on an SDK-driven website or a SkyScribe Site.
SkyScribe is built on the AT Protocol, the same open protocol that powers Bluesky. Authors' content lives in their own Bluesky account, not on a SkyScribe server. You don't need to know the protocol in depth, but a few ideas come up constantly in the SDK.
A handle is a human-readable username, for example alice.bsky.social or anthonycregan.dev. Authors use their handle to identify themselves.
Handles are convenient but not stable: an author can change theirs at any time. So the SDK always resolves a handle to a DID before fetching any data.
A DID is a permanent, globally unique identifier, for example did:plc:abc123. If a handle is like a display name, a DID is like a passport number: it never changes.
There are two DID types you may come across:
| Type | Example | How it works |
|---|---|---|
did:plc | did:plc:abc123 | Managed by the PLC directory at plc.directory. The most common type, used by bsky.social accounts |
did:web | did:web:anthonycregan.dev | Derived from a domain name. The DID document is fetched from https://{domain}/.well-known/did.json |
Every fetch function accepts either a handle or a DID as its author argument. Handles are resolved to DIDs automatically.
The PDS is the server that stores an author's data. All their published content lives there. It may be a shared provider like bsky.social, or a server the author runs themselves.
The SDK finds the right PDS for any author by fetching their DID document and reading its #atproto_pds service entry. This happens automatically: you never need to look up a PDS URL yourself.
Tip
Because the SDK resolves the PDS itself, it works for authors on any PDS, not just bsky.social accounts.
Data on a PDS is organised into collections: named buckets of records. SkyScribe uses two:
| Collection | Contains |
|---|---|
site.standard.publication | Publications, one per website the author publishes to |
site.standard.document | Documents, drafts and published |
Each record has an rkey (record key) that's unique within its collection. For both collections the rkey is an opaque TID (e.g. 3mp4nd46xwr2h) generated by the PDS. You never need to construct one: a Document's human-readable slug is stored in its Publication's record (see DocumentRef), not in the rkey.
A record's full address is an AT URI:
at://{did}/{collection}/{rkey}
at://did:plc:abc123/site.standard.publication/3mp4nd46xwr2h
at://did:plc:abc123/site.standard.document/3mp47vvkh342n
On top of the AT Protocol, SkyScribe organises content in a simple hierarchy: a Publication contains Categories, and Categories contain Documents.
A Publication is the top-level container for everything that appears on one website. It's a single record in the site.standard.publication collection, returned as a StandardPublication, which carries:
uri (the record's AT URI), name, description, domain, basePath (optional path prefix), logoImageUrl, splashImageUrlcategories: the Categories, in order, which hold the published Documentsdomain and basePath together define where the Publication's Documents live:
domain: "anthonycregan.co.uk"
basePath: "blog"
→ Publication root: anthonycregan.co.uk/blog
→ Document: anthonycregan.co.uk/blog/{category-slug}/{document-slug}
When basePath is empty, Categories sit directly under the domain:
domain: "norobots.blog"
basePath: ""
→ Document: norobots.blog/{category-slug}/{document-slug}
domain is a bare domain, with no protocol. buildPublicationUrl(publication) gives the full URL.
Authors set the domain and path prefix in their Publication's settings in SkyScribe (see Publications).
The SDK finds a Publication by its canonical HTTPS URL, the url field of its record. Pass the full URL as the second argument to fetchPublication:
await fetchPublication('alice.bsky.social', 'https://alice.bsky.social');
await fetchPublication('anthonycregan.dev', 'https://norobots.blog');
Internally the SDK scans the author's site.standard.publication collection for the record whose URL matches. You never need to know the record's rkey.
Note
Records written by older tools may also carry a scribe.slug field. The SDK doesn't use it: lookups work entirely from the URL.
A Category is a named, ordered set of Documents within a Publication: a section of the website. Each Category has a slug (its URL segment), a title and its documents. Their order within the Publication is significant, and authors control it in SkyScribe.
A Document is a single piece of writing. All Documents, draft or published, are stored in the site.standard.document collection. A Document belongs to at most one Publication at a time. As a StandardDocument it contains:
uri: the record's AT URItitle, description, content (full HTML), textContent (plain text), path (URL path), coverImageUrltags: optional author-defined stringscontributors: optional DocumentContributor credits (DID, role, display name)site: the AT URI of its Publication once published, e.g. at://did:plc:…/site.standard.publication/3abc (the spec's name for this field)canonicalUrl: the fully qualified URL, e.g. https://myblog.com/blog/creative-writing/my-documentbskyPostRef: the Bluesky post's AT URI and CID, if the author shared the Document to BlueskypublishedAt, updatedAt timestampsSkyScribe works out path and canonicalUrl from the Publication's domain and base path, the Category's slug and the Document's slug when the author publishes. Authors don't type them in.
The Publication record points to its Documents, not the other way round.
Fetching a Publication gives you its whole Document list without any extra requests, because the Publication record contains DocumentRefs: lightweight snapshots of each Document's metadata (title, slug, description, cover image, tags). Only the full content is left out.
That avoids N+1 fetching: render a Document list from the Publication alone, then fetch individual Documents on demand. The Document's slug lives here, and it's what fetchDocumentBySlug matches on.
Note
DocumentRef only exists in code. Authors never see it: in SkyScribe they just see their Documents.
Every Document is in one of two states:
| State | Condition | What it means |
|---|---|---|
| Draft | Exists on the author's PDS; not referenced by any Publication | The author hasn't published it yet. SkyScribe calls this a Standalone Document |
| Published | In a Category of a Publication | It has a canonical URL on the website. Publishing assigns it to the Publication and places it in a Category in one step |
The SDK returns published Documents inside publication.categories[n].documents. fetchPublication never returns drafts: no Publication references them, so there's nothing for the SDK to find them by. (A draft's site field holds a link to its standalone page on the SkyScribe Reader rather than a Publication's AT URI.)
The SDK maps these fields onto its flat StandardPublication and StandardDocument types, so you rarely need the raw records. They're here for when you do.
Fields defined by the site.standard spec (publication, document) live at the top level of a record. Anything SkyScribe-specific lives inside a scribe object on the same record (the Scribe extension), never at the top level. That's also what the "Scribe" in names like ScribeContent and useScribePublication means: they understand the Scribe extension.
site.standard.publication| Field | Notes |
|---|---|
url | Canonical URL, e.g. https://alice.example.com: the lookup key (spec) |
name | Publication name (spec) → name |
description | Optional (spec) |
icon | Optional square image blob (spec) |
scribe.domain / scribe.basePath | Domain and optional path prefix → domain / basePath |
scribe.title | Display title; name falls back to it on older records |
scribe.splashImageUrl / scribe.logoImageUrl | Publication images |
scribe.groups | The ordered Categories, each with a slug, a title and its Document snapshots in articles → categories[].documents |
site.standard.document| Field | Notes |
|---|---|
site | The Publication's AT URI once published (spec) |
title | Required (spec) |
path | URL path, e.g. /essays/a-year-of-letters (spec) |
description | Optional (spec) |
content | The body, as HTML (spec) |
textContent | Plain-text version of the body (spec) |
tags | Optional (spec) |
contributors | Optional { did, role?, displayName? } credits (spec) |
bskyPostRef | Set if the Document was shared to Bluesky (spec) |
publishedAt / updatedAt | Timestamps (spec) |
scribe.createdAt | When the Document was first created |
scribe.coverImageUrl / scribe.canonicalUrl | Cover image source and full public URL |
Draft or published is not a field on the record: it depends entirely on whether a Publication's scribe.groups references the Document.
The record keeps its older field names (scribe.groups, articles); only the SDK's types use the new ones.
SkyScribe's own hosting data (site designs, subscriptions and image library details) is kept in SkyScribe's database, not in the author's account. The SDK only ever reads the content records above, so everything it needs is public and needs no login.
When you call fetchPublication("alice.bsky.social", "https://alice.bsky.social"):
alice.bsky.social to a DID, using Bluesky's public handle-resolution APIsite.standard.publication collection for the record matching the URLStandardPublication with its Categories and DocumentRefs already filled inThe PDS URL is cached in memory for the lifetime of the page, so repeated fetches for the same author don't fetch the DID document again.
Now that you know the model, the Quickstart fetches your first Publication and Document in under five minutes.