Guides
When someone shares a link to a Document on Bluesky, X, Slack or most other platforms, the platform fetches the page and reads its <meta> tags to build a rich preview: a card with a title, description and image. Without these tags, links show up as plain text.
The SDK has helpers that generate Open Graph and Twitter Card tags, a canonical link and structured data from the Document and Publication you've already fetched. They also add the site.standard link tags that tell other apps, Bluesky included, which records a page shows.
For a Document page, the helpers produce:
| Tag | Value |
|---|---|
<title> | "{Document title} — {Publication name}" |
<link rel="canonical"> | Canonical Document URL |
<link rel="site.standard.publication"> | The Publication's AT URI |
<link rel="site.standard.document"> | The Document's AT URI |
description | Document description (when set) |
og:type | "article" |
og:title | Document title |
og:url | Canonical Document URL |
og:site_name | Publication name |
og:description | Document description (when set) |
og:image | Cover image URL (when set) |
twitter:card | "summary_large_image" if there's a cover image, otherwise "summary" |
twitter:title | Document title |
twitter:description | Document description (when set) |
twitter:image | Cover image URL (when set) |
| JSON-LD | A schema.org BlogPosting (headline, dates, author, publisher, image, keywords) |
Add your own { title } after the spread to use your own title format in the browser tab, while the Open Graph tags keep the plain Document title.
Authors can give a Document SEO Settings in SkyScribe: an SEO title, an SEO description and noindex. They're on the Document as document.seo ({ title?, description?, noindex? }; absent when none are set), and the helpers apply them for you:
<title>, og:title and twitter:title. The JSON-LD headline keeps the Document's own title, and so should the page's <h1>.description, og:description and twitter:description tags. Keep showing document.description on the page.<meta name="robots" content="noindex">. Keep the Document on your website and in your feed: it only asks search engines to leave it out. getSitemapEntries already leaves it out of your sitemap.If you override the title, start from the SEO title so the author's choice still counts: document.seo?.title ?? document.title. Values over 200 characters (title) or 500 (description) are ignored, the same way SkyScribe Sites ignore them.
Note
The helpers need the Publication as well as the Document, so your Document page's loader must fetch both. Exactly what each helper covers depends on the framework: the Next.js and Nuxt versions leave out structured data (see each tab).
Use documentMeta from @skyscribe-sdk/react-router-framework. It returns MetaDescriptor[] for React Router's meta export.
// app/routes/blog.$documentSlug.tsx
import { documentMeta } from '@skyscribe-sdk/react-router-framework';
import { fetchDocumentBySlug, fetchPublication } from '@skyscribe-sdk/core';
import type { Route } from './+types/blog.$documentSlug';
export async function loader({ request, params }: Route.LoaderArgs) {
const [document, publication] = await Promise.all([
fetchDocumentBySlug('alice.bsky.social', 'https://alice.bsky.social', params.documentSlug!, request.signal),
fetchPublication('alice.bsky.social', 'https://alice.bsky.social', request.signal),
]);
return { document, publication };
}
export function meta({ loaderData }: Route.MetaArgs) {
if (!loaderData) return [{ title: 'My Blog' }];
return [
...documentMeta(loaderData.document, loaderData.publication),
{ title: `${loaderData.document.seo?.title ?? loaderData.document.title} | My Blog` },
];
}
Use documentMetadata from @skyscribe-sdk/next. It returns a Next.js Metadata object for generateMetadata.
// app/blog/[categorySlug]/[documentSlug]/page.tsx
import { documentMetadata } from '@skyscribe-sdk/next';
import { fetchDocumentBySlug, fetchPublication } from '@skyscribe-sdk/core';
export async function generateMetadata({
params,
}: {
params: Promise<{ documentSlug: string }>;
}) {
const { documentSlug } = await params;
const [document, publication] = await Promise.all([
fetchDocumentBySlug('alice.bsky.social', 'https://alice.bsky.social', documentSlug),
fetchPublication('alice.bsky.social', 'https://alice.bsky.social'),
]);
return {
...documentMetadata(document, publication),
title: `${document.seo?.title ?? document.title} — My Blog`, // override title format if needed
};
}
Metadata has no field for structured data or the site.standard link tags. Render them in the page itself: generateDocumentJsonLd(document, publication) in a <script type="application/ld+json">, and standardSiteLinks(publication, document) as <link> elements (see below). Both are exported from @skyscribe-sdk/next.
The createScribePublication factory's generateDocumentMetadata is simpler: it works from the Publication record plus the Document's SEO Settings, without the canonical URL or Twitter Card. Use documentMetadata when you want the full set.
Use documentSeoMeta from @skyscribe-sdk/nuxt. It returns an object shaped for useSeoMeta().
<!-- pages/blog/[slug].vue -->
<script setup lang="ts">
import { documentSeoMeta, buildCanonicalUrl, generateDocumentJsonLd, standardSiteLinks } from '@skyscribe-sdk/nuxt';
import { fetchDocumentBySlug, fetchPublication } from '@skyscribe-sdk/core';
const route = useRoute();
const [document, publication] = await Promise.all([
fetchDocumentBySlug('alice.bsky.social', 'https://alice.bsky.social', route.params.slug as string),
fetchPublication('alice.bsky.social', 'https://alice.bsky.social'),
]);
useSeoMeta(documentSeoMeta(document, publication));
useHead({
title: `${document.seo?.title ?? document.title} — My Blog`,
link: [
{ rel: 'canonical', href: buildCanonicalUrl(document, publication) },
...standardSiteLinks(publication, document).map(({ rel, href }) => ({ rel, href })),
],
script: [{ type: 'application/ld+json', innerHTML: JSON.stringify(generateDocumentJsonLd(document, publication)) }],
});
</script>
useSeoMeta has no field for a canonical link, link tags or structured data, so those go through useHead. buildCanonicalUrl, standardSiteLinks and generateDocumentJsonLd are re-exported from @skyscribe-sdk/nuxt.
Use generateDocumentMeta from @skyscribe-sdk/core directly. It returns a ScribeMetaTag[] array:
import { generateDocumentMeta } from '@skyscribe-sdk/core';
const tags = generateDocumentMeta(document, publication);
// [
// { title: "My Post — My Blog" },
// { property: "og:type", content: "article" },
// { property: "og:title", content: "My Post" },
// { name: "twitter:card", content: "summary_large_image" },
// ...
// ]
Convert the output to whatever your framework's head management expects. Each element is one of:
{ title: string }: the <title> tag{ tagName: "link"; rel: string; href: string }: the canonical link and the site.standard link tags{ property: string; content: string }: a <meta property="…"> tag{ name: string; content: string }: a <meta name="…"> tag{ "script:ld+json": object }: JSON-LD structured data for a <script type="application/ld+json">The canonical link and og:url use buildCanonicalUrl from @skyscribe-sdk/core, which returns the Document's canonicalUrl. SkyScribe sets that when the author publishes, from the Publication's domain and path prefix, the Category's slug and the Document's slug. Authors don't type it in.
If the canonical URLs point at the wrong address, the Publication's domain or path prefix doesn't match your website. The author fixes that in the Publication's settings in SkyScribe (see Publications), and Documents get the new URL the next time they're published.
Use the Publication variants for pages that list Documents rather than displaying one:
import { publicationMeta } from '@skyscribe-sdk/react-router-framework';
export function meta({ loaderData }: Route.MetaArgs) {
if (!loaderData) return [{ title: 'My Blog' }];
return [
...publicationMeta(loaderData.publication),
{ title: 'My Blog' },
];
}
import { publicationSeoMeta } from '@skyscribe-sdk/nuxt';
useSeoMeta(publicationSeoMeta(publication));
import { generatePublicationMeta } from '@skyscribe-sdk/core';
const tags = generatePublicationMeta(publication);
The site.standard spec lets apps confirm that a web page really shows a given record. Bluesky uses it to show a richer link card, with the Publication's name and icon, when someone shares your page. It needs, server-rendered:
<link rel="site.standard.publication" href="at://…"> on every page, home and Category pages included<link rel="site.standard.document" href="at://…"> on Document pages as wellgeneratePublicationMeta, generateDocumentMeta and the helpers built on them (publicationMeta, documentMeta) include them. For pages that don't use them, standardSiteLinks(publication, document?) returns just the link tags, in the same shape:
// A Category page, React Router
import { standardSiteLinks } from '@skyscribe-sdk/react-router-framework';
export function meta({ loaderData }: Route.MetaArgs) {
if (!loaderData) return [{ title: 'My Blog' }];
return [{ title: `${loaderData.category.title} — My Blog` }, ...standardSiteLinks(loaderData.publication)];
}
Next.js's Metadata has no field for an arbitrary <link rel>, so render them in the page or layout:
import { standardSiteLinks } from '@skyscribe-sdk/next';
{standardSiteLinks(publication, document).map(({ rel, href }) => (
<link key={rel} rel={rel} href={href} />
))}
React 19 (Next.js 15) moves these into the <head>.
The website must also serve the Publication's AT URI at /.well-known/site.standard.publication. A SkyScribe Publication's URL is a bare domain, so it's always at the root. Site Analytics needs it too. The React Router and Next.js packages have ready-made handlers.