What Information Is Captured in the PAGE_TOPOLOGY.md Document?

The PAGE_TOPOLOGY.md document captures a structured blueprint of every section on a target webpage, including visual order, layout geometry, interaction models, and inter-section dependencies to guide automated reconstruction.

The PAGE_TOPOLOGY.md file serves as the assembly blueprint during the reconnaissance phase of the JCodesMore/ai-website-cloner-template repository. This document records exactly what information is captured in the PAGE_TOPOLOGY.md document to enable builder agents to reconstruct layouts accurately. Generated automatically by the clone-website skill according to .github/skills/clone-website/SKILL.md (lines 168-176), it functions as the single source of truth for page-level assembly.

The Role of PAGE_TOPOLOGY.md in the Cloning Pipeline

According to the source code in .github/skills/clone-website/SKILL.md, the topology file is produced during the automated reconnaissance phase. It consolidates DOM inspection data and interaction sweeps into a machine-readable format stored at docs/research/PAGE_TOPOLOGY.md. Builder agents later reference this file to determine where to place components, how they interact, and what global layout constructs—such as scroll containers and z-index layering—must be recreated before wiring individual component specs together.

Seven Categories of Information Captured in PAGE_TOPOLOGY.md

The document systematically records the following data points for every distinct section of the target page:

• Visual order: The sequential list of sections as they appear from top to bottom (e.g., header → hero → features → footer).
• Fixed vs. flow content: Identification of sticky sections that overlay the page versus content that scrolls naturally with the document flow.
• Overall page layout: High-level geometry including scroll containers, column structures, and z-index layering that define relative positioning.
• Dependencies between sections: Relationships such as floating navigation bars that overlay multiple sections or banners that must precede main content.
• Interaction model per section: Classification of behavior types—static, click-driven, scroll-driven, time-driven, or mixed—to ensure correct implementation.
• Section name and purpose: Working identifiers (e.g., "HeroBanner", "FeatureCards") used to generate component filenames and specification files.
• Additional notes: Special constraints like required scroll-snap points or smooth-scroll library dependencies that affect assembly.

How Builder Agents Consume Topology Data

Builder agents read docs/research/PAGE_TOPOLOGY.md to understand the spatial and behavioral relationships between page sections. The topology informs the placement order, interaction implementation, and global layout constructs required for reconstruction. For example, if the topology identifies a sticky header with a z-index of 1000, the builder ensures this layering is preserved in the final src/app/page.tsx assembly stage.

PAGE_TOPOLOGY.md File Structure and Example

The generated markdown follows a consistent template where each section is documented with specific metadata fields. Below is a minimal example illustrating the standard format:

# Page Topology

## 1. Header (sticky)

- **Order:** 1 / 9
- **Layout:** Fixed to top, full-width, z-index 1000
- **Interaction model:** scroll-driven (shrinks after 80 px)
- **Dependencies:** Overlays Hero section

## 2. HeroBanner

- **Order:** 2 / 9
- **Layout:** Full-width, height 80vh, contains background image + CTA button
- **Interaction model:** static
- **Dependencies:** None

## 3. FeaturesGrid

- **Order:** 3 / 9
- **Layout:** 3-column grid (desktop) → 1-column (mobile)
- **Interaction model:** hover-driven (card lift on hover)
- **Dependencies:** None

## 4. Testimonials (scroll-snap)

- **Order:** 4 / 9
- **Layout:** Horizontal scroll container with snap points
- **Interaction model:** scroll-driven (auto-snap)
- **Dependencies:** None

## 5. Footer (static)

- **Order:** 9 / 9
- **Layout:** Flow content, full-width, background #222
- **Interaction model:** static
- **Dependencies:** None

Each entry specifies the Order (sequential position), Layout (structural CSS requirements), Interaction model (behavior type), and Dependencies (relationships with other sections).

Key Source Files and References

The following files define the topology generation and consumption pipeline:

• docs/research/PAGE_TOPOLOGY.md: The generated topology blueprint for a specific target site.
• .github/skills/clone-website/SKILL.md: Documents the cloning pipeline and specifies the output location for the topology file (lines 168-176).
• docs/research/INSPECTION_GUIDE.md: Provides high-level reconnaissance guidance, including the "Page Topology" extraction step.
• src/app/page.tsx: Consumes the topology data to import and arrange built components during final assembly.

Summary

• PAGE_TOPOLOGY.md acts as the assembly blueprint for the AI Website Cloner pipeline, stored at docs/research/PAGE_TOPOLOGY.md.
• The document captures seven critical data categories: visual order, fixed vs. flow content, overall layout geometry, inter-section dependencies, interaction models, section naming, and special constraints.
• Builder agents use this file to reconstruct global page structure before wiring individual component specifications together.
• The clone-website skill automatically generates this document during the reconnaissance phase based on DOM inspection and interaction analysis.

Frequently Asked Questions

What is the primary purpose of PAGE_TOPOLOGY.md in the AI Website Cloner?

The file serves as the single source of truth for page-level assembly, providing builder agents with the spatial layout, interaction models, and dependencies needed to reconstruct a target website's structure accurately according to the topology blueprint.

Where is the PAGE_TOPOLOGY.md file located in the repository?

The document is automatically saved to docs/research/PAGE_TOPOLOGY.md during the clone-website skill execution, as explicitly defined in .github/skills/clone-website/SKILL.md at lines 168-176.

How does the clone-website skill determine what information to include in PAGE_TOPOLOGY.md?

The skill performs automated DOM inspection and interaction sweeps during the reconnaissance phase, extracting visual order, layout geometry, sticky behavior, and interaction patterns directly from the target webpage's source structure.

What is the difference between fixed and flow content in the topology?

Fixed content refers to sticky or overlay sections (like floating navigation bars) that remain visible during scrolling, while flow content scrolls naturally with the document and respects the standard top-to-bottom page flow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}