Files
pages/docs/design/social-link-cards.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

88 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Social link cards (OGP / X)
Implemented 2026-09-14. This is metadata projection, not a public-share or
anonymous-authorization implementation. No visibility settings are changed.
The next publication-policy design is
[Quartier/Spot ownership and superior audience ceilings](locality-publication-ownership.md).
Child settings may restrict but cannot override a superior restriction. This is
not implemented yet; the current enforcing-domain metadata suppression remains.
## Supported projections
Semantic Page/file viewers, all three home layouts, City Map and City details
emit server-rendered Open Graph and `twitter:*` tags in their HTML head. No
JavaScript execution is required by crawlers. Editors, configuration, login,
search, revision/raw endpoints and user-specific utility pages do not acquire
social metadata through this feature.
- Title: first H1 in canonical HTML, otherwise the Page Path; home uses the
Domain title, City detail uses its title.
- Description: plain text from at most 64 KiB of canonical HTML, reduced to
200 Unicode characters. Titles are limited to 90 characters. Scripts, styles,
templates, iframes, SVG, noscript and macro syntax are excluded. Expanded
children, bookmarks, private related pages and embedded documents are never
used as description sources. Non-HTML files use filename / Content-Type.
- Default image: `/static/social-card-v1.png`, a fixed 1200×630 PNG book/academy
emblem. Generated once per process using Go primitives; no external service,
native decoder, font download, scheduler or per-Page cache. GET/HEAD and ETag
requests are supported. It contains no Domain or document data.
- Original image documents: PNG/JPEG/GIF/WebP below 5 MiB use their semantic
`/v/raw/path:{path}` image URL and the `summary` card. Other documents use the
default `summary_large_image`. SVG, oversized images and PDFs use the default;
no thumbnail generation is triggered by a crawler.
- Canonical / image URLs: absolute URLs from the configured effective Domain
FQDN (Domain hostname plus Campus FQDN where applicable), using HTTPS. Localhost
and IP development hosts use the direct HTTP/TLS scheme and matching port.
Forwarded Host/Proto and Origin headers are not canonical-identity sources.
Query parameters/fragments, including tokens, never enter card URLs. Literal
`?`, `#`, `%` and Unicode in Page Paths are URL-encoded exactly once. City
details use their current name-based URL, including the parent for Streets.
## Privacy and operational limits
The existing authorization middleware applies unchanged, including for the
`Twitterbot` User-Agent. With `authorization_mode=enforcing`, anonymous requests
still redirect to authentication; even authenticated HTML contains no card
metadata and adds `noindex, nofollow, noarchive`. Unknown/error authorization
configuration fails closed. Only existing non-enforcing, anonymously readable
deployments emit content cards. Do **not** disable authorization just to enable
cards; narrower anonymous read policy and revocable shared links remain separate
roadmap work. Existing private/no-store HTML response headers are retained.
Once a page has been public, a third party may already retain its metadata/image.
Later revocation prevents new anonymous retrieval but cannot recall third-party
caches. Card layout, refresh timing and final display are controlled by each
sharing service. The application can validate its emitted HTML and image URLs,
not guarantee a card in every post. Public DNS/TLS and reverse-proxy crawl access
must also work. No X account posting/API integration is required or performed.
Canonical HTML is not modified or sanitized by metadata extraction. Normal
document displays now use [inert HTML projections](html-projection-trust.md);
explicit anonymous locality authorization and governance remain separate gates.
## Verification / next slices
`social_metadata_test.go` exercises real rendered heads, Japanese/entity-safe
metadata, bounded extraction, Host spoofing, explicit URL encoding, token
omission, private crawler/authenticated requests, policy revocation, every home
layout, City UUID-to-name canonicalization, real raw image retrieval and the
fallback PNG's dimensions/HEAD/ETag contract.
Future additions: explicit per-Page cover/description settings, approved
Domain-default artwork, precomputed PDF/video/archive cover artifacts, share
projection policy, and a settings preview/diagnostic panel. Do not automatically
fetch arbitrary body image URLs or leak credentials into images.
Deployment follow-up: main `pages.anya.jp` currently redirects anonymous crawlers
to login (303); its public fallback image is reachable via HTTPS. Managed
`wiki.extpages.anya.jp` emits correct tags/image on its local Host-routed listener,
but public HTTPS currently fails with TLS `unrecognized name`. Its certificate /
reverse-proxy virtual host needs correction before external card retrieval can
work. Neither visibility nor external TLS infrastructure was changed here.
Protocol reference: [Open Graph basic and structured metadata](https://ogp.me/).
X compatibility uses the established `twitter:card`, `twitter:title`,
`twitter:description`, `twitter:image` and `twitter:image:alt` fields; its old
developer Cards documentation currently redirects to the general documentation.