[MaartenGr]

Summary

Improves on-page and technical SEO across gemma.ai and bundles sample media assets under docs/assets/:

1. Template-level SEO titles & JSON-LD structured data (overrides/main.html):

   • Overrides {% block htmltitle %} alongside {% block site_meta %} so <title>, og:title, and twitter:title stay in sync.
   • Automatically enriches <title>, og:title, twitter:title, and JSON-LD headlines with the primary model family name from page.meta.models (via partials/model-names.html) whenever a page's title does not already include "Gemma" (e.g., DiffusionGemma — Generate output - Gemma Documentation or LoRA and QLoRA — Gemma 4 - Gemma Documentation).
   • Adds schema.org JSON-LD (<script type="application/ld+json">):
     • WebSite on the homepage with alternateName: ["Gemma Docs", "Google Gemma Documentation", "Gemma AI", "gemma.ai"].
     • TechArticle + BreadcrumbList on all documentation pages.
   • Adds <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1"> (and noindex, nofollow for pages with search.exclude: true).
   • Sets og:type="article" on documentation pages (website on the homepage).

2. docs/robots.txt:

   • Adds docs/robots.txt declaring User-agent: *, Allow: /, and Sitemap: https://gemma.ai/sitemap.xml.

3. Page frontmatter (title, description) and visible <h1> fixes:

   • docs/models/gemma-4/model-card.md: Renames title: Model card to title: Gemma 4 model card (matching all other model cards) and replaces the generic Gemma 1 description with a Gemma 4–specific summary.
   • docs/models/gemma-4/index.md & 4 variant overviews (gemma-3n, embeddinggemma, functiongemma, shieldgemma): Removes {: #hidden-title style="display: none;" } so primary <h1> headings are visible to users and search crawlers, and updates models/gemma-4/index.md with a Gemma 4–specific title and description.
   • Deployment guides (docs/deployment/*.md): Aligns frontmatter title: with each page's # H1 (Run Gemma with Ollama, Serve Gemma with vLLM, etc., matching huggingface.md and keras.md) while keeping compact sidebar labels in zensical.toml.
   • Visual guides & capability pages: Replaces placeholder "— a visual walkthrough." and generic Gemma 1 descriptions with specific summaries, and regenerates docs/llms.txt.

4. Linter guardrails (scripts/frontmatter_schema.py, scripts/lint_docs.py) & tests (tests/test_agent_docs.py):

   • Rejects placeholder "visual walkthrough" descriptions in frontmatter_schema.py.
   • Rejects hidden <h1> tags (#hidden-title / display: none), model cards whose title omits the model name, and pages whose frontmatter title drops "Gemma" when the page's <h1> includes it.

5. Bundle sample media assets (docs/assets/capabilities/):

   • Adds surprise.png, kitchen.jpg, cat.png, and roses-are.wav (previously fetched from https://ai.google.dev/gemma/docs/...) under docs/assets/capabilities/.
   • Updates code snippets in docs/get-started/capabilities/image.md, docs/get-started/capabilities/audio.md, docs/deployment/huggingface.md, docs/deployment/keras.md, and docs/models/embeddinggemma/multimodal.md (plus their 16 generated docs/notebooks/*.ipynb files) to load from https://gemma.ai/assets/....

Verification

• uv run python -m unittest discover -s tests -p "test_*.py" (37 tests passed)
• uv run python scripts/lint_docs.py --baseline (0 new, 0 known findings across all 15 checks)
• uv run python scripts/build_docs.py (verified site/robots.txt and validated all 99 JSON-LD blocks across the built site)

[bebechien]

LGTM!