Files
pages/docs/design/social-link-cards.md
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

5.2 KiB
Raw Permalink Blame History

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. 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; 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. 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.