[MaartenGr]

Summary

This PR establishes the new Zensical-based Gemma documentation foundation. It introduces a new design system, reorganized navigation, model-aware documentation, expanded content, agent-readable surfaces, notebook/Colab support, and a maintainable import and validation pipeline.

What changed

Design and layout

• Introduced a cohesive Gemma design system covering colors, spacing, typography, borders, shadows, and motion.
• Aligned regular and wide-page layouts consistently.
• Added dedicated stylesheets for navigation, content, components, embeds, and page context.
• Refined responsive behavior, sidebars, tables, code blocks, admonitions, cards, and the homepage.
• Added reduced-motion support.
• Removed obsolete and duplicated CSS.

Navigation and content

Reorganized the documentation around user intent:

• Get started
• Models
• Run
• Fine-tune
• Learn
• Demos
• Ecosystem

This includes:

• A model-card-centric Models section.
• Local and production deployment guidance grouped under Run.
• Expanded fine-tuning documentation.
• A task-first Learn landing page.
• New and expanded capability, deployment, tuning, model, and visual-guide pages.
• New Gemma APS, MTP, spoken-language, mobile-action, and learning content.
• Localized documentation images and diagrams.

Model and framework context

• Added centralized model and framework data in data/models.yml and data/frameworks.yml.
• Added a compact context strip showing models, frameworks, example model, and Colab availability.
• Made model names link to their model-card pages.
• Added a persistent global Gemma 4 model selector.
• Added .model-swap support for updating opted-in code examples.
• Added engine-specific identifiers for Ollama, llama.cpp, MLX, vLLM, Transformers, and other runtimes.
• Included Gemma 4 E2B, E4B, 12B, 26B A4B, and 31B variants.
• Added compact framework labels for dense UI.

Markdown and agent-facing documentation

• Added a llms.txt generated from documentation frontmatter.
• Added raw Markdown routes such as /get-started/quickstart.md.
• Added a production build wrapper that generates agent-facing artifacts, runs Zensical, and publishes raw Markdown beside the rendered site.
• Added validated frontmatter for models, frameworks, modalities, prerequisites, and source metadata.
• Added generated model lookup data for templates and browser behavior.

Notebooks and Colab

• Established Markdown as the canonical tutorial source.
• Added explicit .notebook-cell markers for executable examples.
• Added a Markdown-to-Jupyter exporter with stable cell boundaries, shell support, output omission, site-only region removal, nested-fence handling, and Colab metadata.
• Added generated notebooks for nine capability and fine-tuning tutorials.
• Added understated Colab links to the page context strip.
• Positioned Colab consistently as the rightmost context item.

Demos and embeds

• Added a reusable responsive embed component.
• Added an initial Hugging Face Space integration with a plain-link fallback.
• Added the vision token-budget demo page.
• Deferred broader demos and interactive tools until after the core proof of concept.

Import and migration tooling

Preserved the ability to import additional official Gemma Markdown or notebook content safely:

• Manifest-driven, freeze-aware page importer.
• .md.txt/notebook-to-Markdown converter.
• Content-fidelity checker.
• Internal-link rewriter and reviewed link map.
• Optional image vendoring.
• Visual-guide importer.
• Source provenance and frozen-page manifest.

All 63 currently imported pages remain frozen and cannot be accidentally reconverted.

Import-only utilities now live under scripts/importers/, while active build and validation commands remain in scripts/.

Validation and CI

• Added documentation linting for links, images, internal routes, frontmatter, stubs, orphans, code fences, model swapping, admonitions, page size, model data, CSS, and generated artifacts.
• Added a baseline so existing content stubs remain visible without allowing new violations.
• Added regression tests and converter fixtures under tests/.
• Consolidated GitHub Pages deployment into one workflow.
• Added a separate checks workflow.
• Pinned workflow actions and Zensical dependencies.
• Applied least-privilege workflow permissions.
• Removed the unused scaffold and duplicate deployment workflow.

Repository cleanup

• Reduced the root scripts/ directory to active build and validation entry points.
• Moved tests and fixtures into tests/.
• Grouped reusable import utilities under scripts/importers/.
• Replaced the historical planning archive with a concise living roadmap.
• Removed unused generated page metadata and its unstable Git-date calculation.
• Updated contributor documentation and local development instructions.

Verification

• 20 automated tests pass.
• Documentation lint reports zero new findings.
• The remaining six findings are known content stubs recorded in the baseline.
• All 63 imported pages are recognized as frozen and safely skipped.
• The production Zensical/GitHub Pages build succeeds.
• Generated-artifact validation passes.

Follow-up work

• Publish generated notebooks to a dedicated generated-notebooks branch so ordinary Markdown changes do not require committed notebook JSON.
• Decide whether llms.txt should remain committed for local previews or become build-only.
• Resolve the remaining content stubs and upstream keep-or-drop decisions.
• Continue with optional interactive tools, richer demos, and maintainer documentation after the proof of concept is merged.