Site discoverability and performance design

This design covers the public landing page and bilingual documentation metadata. It improves page experience and language discovery without changing product positioning, hosting, application behavior, or documentation content.

Current implementation and verified gaps

The site is static HTML published by GitHub Pages. The landing page already has a canonical URL, description, Open Graph and Twitter cards, SoftwareSourceCode JSON-LD, robots.txt, sitemap.xml, and llms.txt. Documentation pages have absolute canonicals and paired English/Chinese files.

A fresh mobile Lighthouse run against https://openprogram.io/ on 2026-08-13 scored Performance 92, Accessibility 95, Best Practices 100, and SEO 100. The report identified the hero image as the LCP resource at 3.4 seconds, estimated 391 KiB of avoidable image transfer, found one unsized brand image, insufficient contrast in secondary labels, and three copy buttons whose accessible names excluded visible text. Inspection of generated bilingual pages found no reciprocal hreflang links.

Reference corpus and comparison

Reference	Recommended behavior	Current state	Decision
Google Search: localized versions	Every localized page links to itself and all alternates with fully qualified, reciprocal `hreflang` annotations.	Language toggle exists, but search annotations are absent.	Adopt for English/Chinese pairs only.
web.dev: optimize LCP	Make the LCP resource discoverable in initial HTML, avoid lazy loading, and use `fetchpriority="high"` for a likely LCP image.	The image is discoverable and eager, but not priority hinted.	Adopt one high-priority hero image.
web.dev: responsive images	Deliver an image sized for its rendered use and use modern formats where appropriate.	A 3024-pixel, 446 KiB PNG is rendered at about 905 pixels wide on desktop and about 517 pixels in the mobile audit.	Use a dedicated 800-pixel AVIF for the landing page; preserve the original documentation asset.
Google Search: SoftwareApplication data	Software rich results require app-specific properties and truthful offers/rating data.	Current `SoftwareSourceCode` data accurately describes the framework and source repository.	Reject changing the type solely for rich-result eligibility; no rating or commercial offer data exists.
Google Search: breadcrumb data	A `BreadcrumbList` with at least two ordered items can describe a typical visible navigation path.	Documentation pages show breadcrumbs and a linked documentation root but emit no matching structured data.	Adopt a two-level documentation-root and current-page trail; omit it from the documentation root itself.

Target behavior and boundaries

The landing hero uses a dedicated AVIF, retains intrinsic dimensions, is present in initial HTML, and is the only image marked fetchpriority="high".
Every landing image has explicit width and height. Secondary text meets WCAG AA contrast. Copy buttons derive their accessible names from their visible content. The word program receives a distinct high-contrast brand color while the surrounding headline retains its gradient.
Each generated English/Chinese documentation pair emits identical reciprocal annotations for en, zh-Hans, and x-default; the English URL is the fallback. Unpaired pages emit no incomplete language cluster.
Canonical URLs remain self-referential. Existing language-toggle behavior remains unchanged.
Each generated documentation content page emits one BreadcrumbList for OpenProgram Docs → current page. The documentation root emits none, avoiding a fabricated second level.
No analytics, tracking, cookie banner, new runtime dependency, CDN migration, or hosting change is introduced. GitHub Pages cache headers are outside repository control.

Failure and compatibility behavior

The build derives alternates only from the page pair already discovered by the documentation scanner. URLs are generated from the same site origin and deployment base as canonicals, preventing relative or cross-origin annotations. If a pair does not exist, the page remains valid and canonical without hreflang. Breadcrumb JSON is serialized by the Python standard library and escapes opening angle brackets so a page title cannot terminate the script element. PNG assets remain available for documentation and existing links.

Acceptance criteria

python -m tools.docs_site.check_landing rejects the old landing markup and old bilingual build, then passes the final candidate.
python -m tools.docs_site.build and python -m tools.docs_site.checklinks pass.
The optimized hero is materially smaller than the existing PNG and has the declared intrinsic dimensions.
Fresh mobile Lighthouse has no failures for unsized images, color contrast, label-content-name mismatch, image delivery, or LCP discovery; SEO and Best Practices remain 100.
Full repository CI passes on the reviewed commit, the commit is contained in origin/main, and the deployed page reproduces the verified markup.
The generated documentation root contains no BreadcrumbList; every canonical content page contains exactly one valid two-item trail rooted at https://openprogram.io/docs/.

Implementation evidence

Implementation commit e554b1b5 passed independent specification and code-quality review after the acceptance checks were tightened to validate the primary AVIF item, its <picture> association, fallback dimensions, and semantic hreflang attributes.
Pull request #3 was merged as e1fb4d55. CI run 31655884877 passed documentation, Web, and Python 3.11/3.12/3.13 jobs after rerunning one unrelated cascade-cancellation timing failure.
The publish workflow produced site commit b16efa3; Pages deployment 31656714682 passed. Live HTML and asset probes confirmed the emphasized program text, AVIF response, high-priority hero, and reciprocal English/Chinese annotations.
A fresh mobile Lighthouse audit of the deployed site scored Performance 100, Accessibility 100, Best Practices 100, and SEO 100, with LCP 1.0 seconds and no binary audit failures.
Pull request #5 merged as c586299e after Web, documentation, and Python 3.11–3.13 CI passed. Publish run 31659339733 succeeded; live probes confirmed the two-item BreadcrumbList, the v0.6.0 documentation links, and the current Chinese self-programming positioning.