Getting started

Core concepts

This page covers two things: how SkyScribe identifies you (your Bluesky identity), and how it organises what you write (the content model). Every other part of the guide builds on these.

Your identity

SkyScribe does not have its own accounts. You sign in with Bluesky, and your Bluesky identity is your identity in SkyScribe.

Handle

Your handle is your readable username — alice.bsky.social, or a custom one like alice.com. It is how people refer to you, but it is not permanent — you can change it whenever you like.

Behind the handle is a DID (Decentralized Identifier) — a permanent ID such as did:plc:abc123 that never changes, even if your handle does. SkyScribe and the SDK always resolve a handle to its DID before doing anything with your content, so a handle change never breaks your links.

PDS

Your PDS (Personal Data Server) is the server that actually stores your data — your posts, and all your SkyScribe content. It might be Bluesky's own servers or one you host yourself. Either way, SkyScribe writes your content there, and any reader (a SkyScribe Site, an SDK site) reads it back from there.

Note

This is why your content is portable: it is standard AT Protocol data sitting in your account, not rows in a SkyScribe-only database.

The content model

SkyScribe organises writing into three nested levels, plus one hosting concept.

Publication

A Publication is a container for a body of related content — think of it as one blog or one magazine. You can have several. Each Publication has a title, a description, and a set of Categories.

Under the hood a Publication is a single site.standard.publication record on your PDS.

Document

A Document is one piece of writing: a title, an optional summary and cover image, optional tags, and the body content you wrote in the editor. A Document belongs to at most one Publication at a time, and sits in exactly one Category within it.

Builder Site

A Builder Site is a hosted, wizard-designed website bound to one Publication. It is the thing a PRO subscription's Site Slot pays for. Unlike the three concepts above, a Builder Site is not AT Protocol data — it is SkyScribe's hosting of a design you configured. A Publication can have a Builder Site, be read by a hand-built SDK site, both, or neither.

How they nest

Publication:  "Alice writes"
├── Category:  Essays
│   ├── Document:  On slowness
│   └── Document:  A year of letters
└── Category:  Notes
    └── Document:  Bookmarks, March

Draft and Published

Every Document is in one of two states:

State	What it means
Draft	The Document exists in your account but is not attached to any Publication. Only you can see it.
Published	The Document has been placed in a Category within a Publication. It now has a public URL and any connected website can show it.

Publishing picks a Publication and a Category together, in one step. Unpublishing reverses it and returns the Document to Draft — nothing is deleted, and you can publish it again anytime.

One vocabulary, three name-sets

SkyScribe deliberately uses its own names. The AT Protocol records they map to have technical names, the SDK exposes them to developers under yet different names, and the older Scribe CMS app uses another set again. This guide always uses the SkyScribe column; this table is the key.

This guide (SkyScribe)	AT Protocol record / field	SDK type	Scribe CMS
Publication	`site.standard.publication`	`Site` (`fetchSite`)	"Site"
Document	`site.standard.document`	`Article` (`fetchArticle`)	"Article"
Category	`scribe.groups[]` on the publication record	`Group`	"Group"
Builder Site	— (SkyScribe hosting, not PDS data)	—	—

Tip

If you only ever use the SkyScribe app and SkyScribe Sites, you can ignore the other three columns entirely. They matter once you read the Build your own frontend section, where the SDK's own names are unavoidable.

SkyScribe Sites vs. your own frontend walks through the choice between a hosted site and building your own.