Update README.md

src/landings/README.md

@@ -1,63 +1,128 @@
-# Landing pages
+# 🏠 Landing Pages
 
-The landings subject provides components and logic for rendering various types of landing pages across docs.github.com, including the Docs home page, category pages, and specialized layouts like journey, discovery, and bespoke landings.
+The **Landing Pages** subject powers the various landing page experiences across **docs.github.com**. It provides the components, data processing, and rendering logic required to generate the Docs homepage, category pages, guided journeys, discovery pages, and other custom landing experiences.
 
-## Purpose & Scope
+Landing pages act as navigation hubs, helping users quickly discover relevant documentation through curated content, hierarchical navigation, and featured resources.
+
+---
+
+## ✨ Responsibilities
 
 This subject is responsible for:
-- Rendering different landing page layouts (toc, category, journey, discovery, bespoke)
-- Building and displaying featured links, article cards, and guide cards
+
+- Rendering multiple landing page layouts
+- Building hierarchical navigation from the documentation tree
+- Displaying featured links, guide cards, and article cards
 - Managing landing page context and data requirements
-- Providing hierarchical navigation for products and categories
-- Displaying article carousels
+- Supporting product and category navigation
+- Rendering article carousels and curated content sections
+
+---
+
+## 🗂️ Supported Landing Page Types
+
+| Landing Page | Layout | Description |
+|--------------|--------|-------------|
+| **Category Landing** | `category-landing` | Category overview pages with hierarchical navigation |
+| **Table of Contents** | `toc-landing` | Documentation index pages generated from the content tree |
+| **Journey Landing** | `journey-landing` | Guided learning experiences with track-based navigation |
+| **Discovery Landing** | `discovery-landing` | Curated pages designed for exploration and content discovery |
+| **Bespoke Landing** | `bespoke-landing` | Fully custom, hand-crafted landing pages |
+| **Docs Home** | *(special)* | The main homepage for docs.github.com |
+
+---
 
-Landing pages serve as navigational hubs that provide a hierarchical view of their area, making it easier to find and discover documentation.
+## 🏗️ Architecture
 
-## Architecture & Key Assets
+Landing pages are generated using a combination of:
 
-| Landing Page Type | Layout Value | Purpose |
-|-------------------|--------------|---------|
-| Category landing | `category-landing` | Category pages with hierarchical navigation |
-| Table of contents | `toc-landing` | Table of contents pages |
-| Journey landing | `journey-landing` | Guided learning journey pages with track navigation |
-| Discovery landing | `discovery-landing` | Discovery/exploration pages |
-| Bespoke landing | `bespoke-landing` | Custom hand-built landing pages |
-| Home page | (special) | Docs.github.com homepage |
+- **Page frontmatter** for layout configuration
+- **Content tree** for hierarchical navigation
+- **Product metadata** for product-specific information
+- **React components** for rendering page layouts
+- **Context builders** for supplying page-specific data
 
-## Setup & Usage
+The selected `layout` value determines which landing page component is rendered.
 
-### Running tests
+---
+
+## 🚀 Running Tests
+
+Run the landing page test suite:
 
 ```bash
 npm run test -- src/landings/tests
 ```
 
-## Data & External Dependencies
+---
+
+## 📥 Data Inputs
+
+Landing pages consume data from several sources:
+
+| Source | Purpose |
+|---------|---------|
+| Page Frontmatter | Defines layout, featured links, journey tracks, and page-specific configuration |
+| Content Tree | Generates navigation hierarchies and table of contents |
+| Product Metadata | Supplies product names, versions, and release information |
+
+Common frontmatter fields include:
+
+- `layout`
+- `featuredLinks`
+- `journeyTracks`
+- Other landing page configuration values
+
+---
+
+## 🔗 Dependencies
+
+This subject integrates with several other parts of the documentation system.
+
+| Module | Purpose |
+|--------|---------|
+| `@/frame` | Shared context object, page data, and common components |
+| `@/content-render` | Renders Liquid templates in featured link titles |
+| `@/journeys` | Journey track data and React components |
+| `@/products` | Product metadata and grouping logic |
+| `@/versions` | Version-aware content filtering |
+
+---
+
+## 📤 Outputs
+
+After processing, the landing page system produces:
+
+- `req.context.featuredLinks`
+- Landing page context objects
+- Hierarchical navigation structures
+- Rendered React landing pages
+- Final HTML output
+
+---
+
+## ⚠️ Current Limitations
+
+Some known constraints include:
+
+- Multiple landing page implementations with overlapping functionality
+- Featured links are limited to **four per category** to prevent overly tall layouts
+- Bespoke landing pages require custom React components instead of a fully data-driven configuration
+
+---
 
-### Data inputs
-- Page frontmatter: `layout`, `featuredLinks`, `journeyTracks`, etc.
-- Content tree: Used to build TOC and navigation hierarchies
-- Product metadata: Product names, versions, release information
+## 🚀 Future Improvements
 
-### Dependencies
-- [`@/frame`](../frame/README.md) - Context object, page data, shared components
-- [`@/content-render`](../content-render/README.md) - Renders Liquid in featured link titles
-- [`@/journeys`](../journeys/README.md) - Journey track components and data
-- [`@/products`](../products/README.md) - Product metadata and groupings
-- [`@/versions`](../versions/README.md) - Version-aware content filtering
+Potential areas for enhancement include:
 
-### Data outputs
-- `req.context.featuredLinks` - Resolved featured link data
-- Landing page contexts - Various context objects passed to React components
-- Rendered landing pages - Final HTML output
+- Consolidating similar landing page implementations
+- Standardizing landing page patterns across layouts
+- Expanding the use of reusable components
+- Moving toward a more data-driven architecture
+- Reducing custom rendering logic where possible
 
-## Current State & Next Steps
+---
 
-### Known limitations
-- Multiple similar but distinct landing components (could be consolidated)
-- Featured links limited to 4 per category to avoid overly tall columns
-- Bespoke landing pages require custom components rather than data-driven approach
+## 📚 Summary
 
-### Areas for improvement
-- Standardize landing page patterns and consolidate overlapping types
-- Make landing pages more data-driven and less code-heavy
+The **Landing Pages** subject serves as the central navigation layer for **docs.github.com**, transforming structured content and metadata into intuitive landing experiences that help users discover documentation efficiently.