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.
88 lines
5.2 KiB
Markdown
88 lines
5.2 KiB
Markdown
# 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.
|