Guides
A StandardPublication carries two URL-related fields that together define the root of its Documents:
| Field | Example | Meaning |
|---|---|---|
publication.domain | "anthonycregan.co.uk" | The Publication's domain (no protocol) |
publication.basePath | "blog" | Path prefix for its Documents: an empty string if they're at the root |
A Document's own slug is slug on its DocumentRef.
The canonical URL for a published Document is:
https://{publication.domain}/{publication.basePath}/{category.slug}/{ref.slug}
When basePath is empty, the pattern is:
https://{publication.domain}/{category.slug}/{ref.slug}
@skyscribe-sdk/core has two helpers:
buildPublicationUrl(publication) returns the Publication's root, e.g. https://anthonycregan.co.uk/blogbuildCanonicalUrl(document, publication) returns a full StandardDocument's canonical URL. It uses the canonicalUrl SkyScribe stored when the Document was publishedTo build a URL from a DocumentRef (from fetchPublication, without fetching each Document), write a small helper once and reuse it:
import type { StandardPublication } from '@skyscribe-sdk/core';
function documentUrl(publication: StandardPublication, categorySlug: string, documentSlug: string): string {
const base = publication.basePath
? `https://${publication.domain}/${publication.basePath}`
: `https://${publication.domain}`;
return `${base}/${categorySlug}/${documentSlug}`;
}
Usage:
const url = documentUrl(publication, category.slug, ref.slug);
// e.g. "https://anthonycregan.co.uk/blog/2024/my-first-post"
// or "https://norobots.blog/2024/my-first-post"
Tip
When building internal links within your own website, use relative paths (/blog/2024/my-first-post) rather than absolute URLs. The absolute form is for canonical <link> tags, RSS items, and sitemap entries.
Pass the Publication's canonical HTTPS URL straight to fetchPublication:
import { fetchPublication } from '@skyscribe-sdk/core';
await fetchPublication('alice.bsky.social', 'https://alice.bsky.social');
await fetchPublication('anthonycregan.dev', 'https://anthonycregan.co.uk');
await fetchPublication('anthonycregan.dev', 'https://norobots.blog');
(toSlug is still exported from @skyscribe-sdk/core, but lookups no longer need it.)
A Document's human-readable slug is on the DocumentRef objects returned by fetchPublication. Use ref.slug; don't try to derive it from the AT URI.
const publication = await fetchPublication('alice.bsky.social', 'https://alice.bsky.social');
for (const category of publication.categories) {
for (const ref of category.documents) {
if (!ref.slug) continue; // very old records may lack one
const url = documentUrl(publication, category.slug, ref.slug);
}
}
Document rkeys are opaque TIDs (e.g. 3mp47vvkh342n) assigned by the PDS. slugFromUri returns that TID, which is not the human-readable slug, so use ref.slug when building URLs.