Someone pastes your docs URL into Slack or LinkedIn. What title, description, and preview image do they see? And where do visitors find your GitHub or Discord without hunting through the prose? docs.page answers both questions from docs.json: footer icons for your profiles, and Open Graph metadata for link previews.
Social configuration splits across two concerns in docs.json:
social: profile shortcuts rendered as icon buttons in the site footer.og: inputs that shape auto-generated share-card images when no static preview image is set.
A third top-level field, socialPreview, sets a default preview image for every page. Per-page frontmatter can override that image. Together, these settings control outbound sharing and the footer area where community links appear.
Field names, types, and defaults live on the docs.json. This page explains how the pieces fit together.
Add a social object to docs.json. Each key is a supported platform; the value is a handle, ID, or URL fragment, not a full profile URL (except website):
{
"social": {
"website": "https://acme.dev",
"github": "acme",
"x": "acme",
"discord": "acme-community"
}
}docs.page maps each key to the correct destination, for example github: "acme" becomes https://github.com/acme, and discord: "acme-community" becomes https://discord.gg/acme-community.
Supported platforms: website, x, youtube, facebook, instagram, linkedin, github, slack, and discord. Entries with empty values or unknown keys are skipped. The footer sorts remaining icons alphabetically by key so the order stays consistent on server and client renders.
These icons sit in the footer beside the docs.page attribution, separate from header links (top-bar CTAs) and anchor links (sidebar shortcuts). Use footer social icons when you want profile links on every page without competing for header or sidebar space.
Each published page emits standard meta tags for title, description, and preview image: both Open Graph (og:*) and Twitter Card (twitter:*) variants. The renderer resolves values in a predictable cascade:
| Field | Resolution order |
|---|---|
| Title | Page frontmatter title → name in docs.json → "Documentation" |
| Description | Page frontmatter description → description in docs.json |
| Preview image | Page frontmatter image → socialPreview in docs.json → auto-generated card |
Canonical URLs and seo.noindex come from other configuration surfaces; see Search engine indexing when you need to block crawlers.
When neither page frontmatter nor socialPreview supplies an image, docs.page builds one dynamically. It sends the resolved title, description, logo, and optional repository identifier to an OG image endpoint and uses the result as og:image.
The og object in docs.json controls what goes into that generated card:
og.logo: a repo-relative path underdocs/or an absolute URL for the logo on the card. When omitted, docs.page falls back tologo.dark, thenlogo.light, from your logo configuration.og.github: whentrue(the default), the generated card includes your GitHub repository (owner/repofrom the hosted source). Set tofalseto omit the repository badge.
Set socialPreview to a static image URL when you want the same artwork on every page without generation, useful for a branded default. Individual pages can still override it with frontmatter image. See Page frontmatter for per-page metadata fields.