8.3 KiB

Raw Blame History

Story 3.4: Boilerplate Site Pages - CREATED

Status: Specification Complete, Ready for Implementation
Date Created: October 21, 2025

Summary

Story 3.4 has been created to address the broken navigation menu links introduced in Story 3.3.

The Problem

In Story 3.3, we added navigation menus to all HTML templates:

<nav>
  <ul>
    <li><a href="/index.html">Home</a></li>
    <li><a href="about.html">About</a></li>
    <li><a href="privacy.html">Privacy</a></li>
    <li><a href="contact.html">Contact</a></li>
  </ul>
</nav>

However, we never created the about.html, contact.html, or privacy.html pages, resulting in broken links.

The Solution

Story 3.4 will automatically generate these boilerplate pages for each site during batch generation.

What Will Be Delivered

1. Three Boilerplate Pages Per Site (Heading Only)

About Page (about.html) - <h1>About Us</h1> + template/navigation
Contact Page (contact.html) - <h1>Contact</h1> + template/navigation
Privacy Policy (privacy.html) - <h1>Privacy Policy</h1> + template/navigation

All pages have just a heading wrapped in the template structure. No other content text. User can add content manually later if desired.

2. Database Storage

New site_pages table stores pages separately from articles:

CREATE TABLE site_pages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    site_deployment_id INTEGER NOT NULL,
    page_type VARCHAR(20) NOT NULL,  -- about, contact, privacy
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (site_deployment_id) REFERENCES site_deployments(id),
    UNIQUE (site_deployment_id, page_type)
);

3. Template Integration

Pages use the same template as articles on the same site
Template read from site.template_name field in database
Professional, visually consistent with article content
Navigation menu included (which links to these same pages)

4. Smart Generation

Generated ONLY when new sites are created (not for existing sites)
One-time backfill script for all existing imported sites
Integrated into site creation workflow (not batch generation)

Implementation Scope

Effort Estimate

14 story points (reduced from 20, approximately 1.5-2 days of development)

Simplified due to:

Heading-only pages (no complex content generation)
No template service changes needed (template tracked in database)
No database tracking overhead (just check if files exist on bunny.net)

Key Components

Database Schema (2 points)
- New SitePage model
- Migration script
- Repository layer
Page Content Templates (1 point - simplified)
- Heading-only page content
- Returns <h1>About Us</h1>, <h1>Contact</h1>, <h1>Privacy Policy</h1>
- No complex content generation
Generation Logic (2 points - simplified)
- Generate heading-only pages for each site
- Wrap heading in HTML template
- Store in database
Site Creation Integration (2 points)
- Hook into site_provisioning.py
- Generate pages when new sites are created
- Handle errors gracefully
Backfill Script (2 points)
- CLI script to generate pages for all existing sites
- Dry-run mode for safety
- Progress reporting and error handling
Testing (3 points - simplified)
- Unit tests for heading-only page generation
- Integration tests with site creation
- Backfill script testing
- Template application tests

Total: 14 story points (reduced from 20)

Integration Point

Story 3.4 hooks into site creation, not batch generation:

One-Time Setup (Existing Sites)

# Backfill all existing imported sites (hundreds of sites)
uv run python scripts/backfill_site_pages.py \
  --username admin \
  --password yourpass \
  --template basic

# Output: Generated pages for 423 sites

Ongoing (New Sites Only)

When creating new sites:
1. Create Storage Zone (bunny.net)
2. Create Pull Zone (bunny.net)
3. Save to database
4. ✨ Generate boilerplate pages (Story 3.4) ← NEW
5. Return site ready to use

Triggered by:
- provision-site CLI command
- auto_create_sites in job config
- create_sites_for_keywords in job config

Batch Generation (Unchanged)

1. Generate articles (Epic 2)
2. Assign sites (Story 3.1) ← May use existing sites with pages
3. Generate URLs (Story 3.1)
4. Find tiered links (Story 3.2)
5. Inject interlinks (Story 3.3)
6. Apply templates (Story 2.4)
7. Deploy (Epic 4) ← Pages already exist on site

Files Created

Documentation

docs/stories/story-3.4-boilerplate-site-pages.md (full specification)
docs/prd/epic-3-pre-deployment.md (updated to include Story 3.4)
STORY_3.4_CREATED.md (this summary)

Implementation Files (To Be Created)

src/generation/page_templates.py - Generic page content
src/generation/site_page_generator.py - Page generation logic
src/database/models.py - SitePage model (update)
scripts/migrate_add_site_pages.py - Database migration
scripts/backfill_site_pages.py - One-time backfill script
tests/unit/test_site_page_generator.py - Unit tests
tests/integration/test_site_pages_integration.py - Integration tests
tests/unit/test_backfill_script.py - Backfill script tests

Dependencies

Requires (Already Complete)

✅ Story 3.1: Site assignment (need to know which sites are in use)
✅ Story 3.3: Navigation menus (these pages fulfill those links)
✅ Story 2.4: Template service (for applying HTML templates)
✅ Story 1.6: SiteDeployment table (for site relationships)

Enables

Story 4.1: Deployment (pages will be deployed along with articles)
Complete, professional-looking sites with working navigation

Example Output

Site Structure After Story 3.4

https://example.com/
├── index.html                        (homepage - future/Epic 4)
├── about.html                        ← NEW (Story 3.4)
├── contact.html                      ← NEW (Story 3.4)
├── privacy.html                      ← NEW (Story 3.4)
├── how-to-fix-your-engine.html      (article)
├── engine-maintenance-tips.html     (article)
└── best-engine-oil-brands.html      (article)

About Page Preview (Heading Only)

<!DOCTYPE html>
<html>
<head>
    <title>About Us</title>
    <!-- Same template/styling as articles -->
</head>
<body>
    <nav>
        <ul>
            <li><a href="/index.html">Home</a></li>
            <li><a href="about.html">About</a></li>
            <li><a href="privacy.html">Privacy</a></li>
            <li><a href="contact.html">Contact</a></li>
        </ul>
    </nav>
    
    <main>
        <h1>About Us</h1>
        <!-- No other content - user can add manually later if desired -->
    </main>
</body>
</html>

Why heading-only pages?

Fixes broken navigation links (no 404 errors)
Better UX than completely blank (user sees page title)
Minimal implementation effort
User can customize specific sites later if needed
Deployment ready as-is

Next Steps

Option 1: Implement Now

Start implementation of Story 3.4
Fixes broken navigation links
Makes sites look complete and professional

Option 2: Defer to Later

Add to backlog/technical debt
Focus on Epic 4 deployment first
Sites work but have broken nav links temporarily

Option 3: Minimal Quick Fix

Create simple placeholder pages without full story implementation
Just enough to avoid 404 errors
Come back later for full implementation

Recommendation

Implement Story 3.4 before Epic 4 deployment because:

Sites look unprofessional with broken nav links
Fixes 404 errors on every deployed site
Only 15 story points (1.5-2 days) - simplified implementation
Empty pages are deployment-ready
User can add content to specific pages later if desired

The alternative is to deploy with broken links and fix later, but that creates technical debt and poor user experience.

Simplified approach: Pages have heading only (e.g., <h1>About Us</h1>), no body content. This makes implementation faster while still fixing the broken link issue and providing better UX than completely blank pages.

Created by: AI Code Assistant
Created on: October 21, 2025
Next: Decide when to implement Story 3.4 (now vs. later vs. minimal fix)

8.3 KiB Raw Blame History