Skip to content

Commit f547efc

Browse files
krishnavas23krishnavas23
authored
Update README.md
1 parent a385982 commit f547efc

1 file changed

Lines changed: 107 additions & 42 deletions

File tree

‎src/landings/README.md‎

Lines changed: 107 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,128 @@
1-
# Landing pages
1+
# 🏠 Landing Pages
22

3-
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.
3+
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.
44

5-
## Purpose & Scope
5+
Landing pages act as navigation hubs, helping users quickly discover relevant documentation through curated content, hierarchical navigation, and featured resources.
6+
7+
---
8+
9+
## ✨ Responsibilities
610

711
This subject is responsible for:
8-
- Rendering different landing page layouts (toc, category, journey, discovery, bespoke)
9-
- Building and displaying featured links, article cards, and guide cards
12+
13+
- Rendering multiple landing page layouts
14+
- Building hierarchical navigation from the documentation tree
15+
- Displaying featured links, guide cards, and article cards
1016
- Managing landing page context and data requirements
11-
- Providing hierarchical navigation for products and categories
12-
- Displaying article carousels
17+
- Supporting product and category navigation
18+
- Rendering article carousels and curated content sections
19+
20+
---
21+
22+
## 🗂️ Supported Landing Page Types
23+
24+
| Landing Page | Layout | Description |
25+
|--------------|--------|-------------|
26+
| **Category Landing** | `category-landing` | Category overview pages with hierarchical navigation |
27+
| **Table of Contents** | `toc-landing` | Documentation index pages generated from the content tree |
28+
| **Journey Landing** | `journey-landing` | Guided learning experiences with track-based navigation |
29+
| **Discovery Landing** | `discovery-landing` | Curated pages designed for exploration and content discovery |
30+
| **Bespoke Landing** | `bespoke-landing` | Fully custom, hand-crafted landing pages |
31+
| **Docs Home** | *(special)* | The main homepage for docs.github.com |
32+
33+
---
1334

14-
Landing pages serve as navigational hubs that provide a hierarchical view of their area, making it easier to find and discover documentation.
35+
## 🏗️ Architecture
1536

16-
## Architecture & Key Assets
37+
Landing pages are generated using a combination of:
1738

18-
| Landing Page Type | Layout Value | Purpose |
19-
|-------------------|--------------|---------|
20-
| Category landing | `category-landing` | Category pages with hierarchical navigation |
21-
| Table of contents | `toc-landing` | Table of contents pages |
22-
| Journey landing | `journey-landing` | Guided learning journey pages with track navigation |
23-
| Discovery landing | `discovery-landing` | Discovery/exploration pages |
24-
| Bespoke landing | `bespoke-landing` | Custom hand-built landing pages |
25-
| Home page | (special) | Docs.github.com homepage |
39+
- **Page frontmatter** for layout configuration
40+
- **Content tree** for hierarchical navigation
41+
- **Product metadata** for product-specific information
42+
- **React components** for rendering page layouts
43+
- **Context builders** for supplying page-specific data
2644

27-
## Setup & Usage
45+
The selected `layout` value determines which landing page component is rendered.
2846

29-
### Running tests
47+
---
48+
49+
## 🚀 Running Tests
50+
51+
Run the landing page test suite:
3052

3153
```bash
3254
npm run test -- src/landings/tests
3355
```
3456

35-
## Data & External Dependencies
57+
---
58+
59+
## 📥 Data Inputs
60+
61+
Landing pages consume data from several sources:
62+
63+
| Source | Purpose |
64+
|---------|---------|
65+
| Page Frontmatter | Defines layout, featured links, journey tracks, and page-specific configuration |
66+
| Content Tree | Generates navigation hierarchies and table of contents |
67+
| Product Metadata | Supplies product names, versions, and release information |
68+
69+
Common frontmatter fields include:
70+
71+
- `layout`
72+
- `featuredLinks`
73+
- `journeyTracks`
74+
- Other landing page configuration values
75+
76+
---
77+
78+
## 🔗 Dependencies
79+
80+
This subject integrates with several other parts of the documentation system.
81+
82+
| Module | Purpose |
83+
|--------|---------|
84+
| `@/frame` | Shared context object, page data, and common components |
85+
| `@/content-render` | Renders Liquid templates in featured link titles |
86+
| `@/journeys` | Journey track data and React components |
87+
| `@/products` | Product metadata and grouping logic |
88+
| `@/versions` | Version-aware content filtering |
89+
90+
---
91+
92+
## 📤 Outputs
93+
94+
After processing, the landing page system produces:
95+
96+
- `req.context.featuredLinks`
97+
- Landing page context objects
98+
- Hierarchical navigation structures
99+
- Rendered React landing pages
100+
- Final HTML output
101+
102+
---
103+
104+
## ⚠️ Current Limitations
105+
106+
Some known constraints include:
107+
108+
- Multiple landing page implementations with overlapping functionality
109+
- Featured links are limited to **four per category** to prevent overly tall layouts
110+
- Bespoke landing pages require custom React components instead of a fully data-driven configuration
111+
112+
---
36113

37-
### Data inputs
38-
- Page frontmatter: `layout`, `featuredLinks`, `journeyTracks`, etc.
39-
- Content tree: Used to build TOC and navigation hierarchies
40-
- Product metadata: Product names, versions, release information
114+
## 🚀 Future Improvements
41115

42-
### Dependencies
43-
- [`@/frame`](../frame/README.md) - Context object, page data, shared components
44-
- [`@/content-render`](../content-render/README.md) - Renders Liquid in featured link titles
45-
- [`@/journeys`](../journeys/README.md) - Journey track components and data
46-
- [`@/products`](../products/README.md) - Product metadata and groupings
47-
- [`@/versions`](../versions/README.md) - Version-aware content filtering
116+
Potential areas for enhancement include:
48117

49-
### Data outputs
50-
- `req.context.featuredLinks` - Resolved featured link data
51-
- Landing page contexts - Various context objects passed to React components
52-
- Rendered landing pages - Final HTML output
118+
- Consolidating similar landing page implementations
119+
- Standardizing landing page patterns across layouts
120+
- Expanding the use of reusable components
121+
- Moving toward a more data-driven architecture
122+
- Reducing custom rendering logic where possible
53123

54-
## Current State & Next Steps
124+
---
55125

56-
### Known limitations
57-
- Multiple similar but distinct landing components (could be consolidated)
58-
- Featured links limited to 4 per category to avoid overly tall columns
59-
- Bespoke landing pages require custom components rather than data-driven approach
126+
## 📚 Summary
60127

61-
### Areas for improvement
62-
- Standardize landing page patterns and consolidate overlapping types
63-
- Make landing pages more data-driven and less code-heavy
128+
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.

0 commit comments

Comments
 (0)