282 lines
8.3 KiB
Markdown
282 lines
8.3 KiB
Markdown
# 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:
|
|
```html
|
|
<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:
|
|
```sql
|
|
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
|
|
|
|
1. **Database Schema** (2 points)
|
|
- New `SitePage` model
|
|
- Migration script
|
|
- Repository layer
|
|
|
|
2. **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
|
|
|
|
3. **Generation Logic** (2 points - simplified)
|
|
- Generate heading-only pages for each site
|
|
- Wrap heading in HTML template
|
|
- Store in database
|
|
|
|
4. **Site Creation Integration** (2 points)
|
|
- Hook into `site_provisioning.py`
|
|
- Generate pages when new sites are created
|
|
- Handle errors gracefully
|
|
|
|
5. **Backfill Script** (2 points)
|
|
- CLI script to generate pages for all existing sites
|
|
- Dry-run mode for safety
|
|
- Progress reporting and error handling
|
|
|
|
6. **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)
|
|
```bash
|
|
# 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)
|
|
```html
|
|
<!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:
|
|
|
|
1. Sites look unprofessional with broken nav links
|
|
2. Fixes 404 errors on every deployed site
|
|
3. Only 15 story points (1.5-2 days) - simplified implementation
|
|
4. Empty pages are deployment-ready
|
|
5. 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)
|
|
|