# TCBA Website Modernization Guide
> A comprehensive guide for converting legacy Word/Excel-generated HTML pages to modern, accessible, and maintainable web pages.
## Table of Contents
1. [Overview](#overview)
2. [HTML Structure Standards](#html-structure-standards)
3. [CSS Architecture](#css-architecture)
4. [Theme System](#theme-system)
5. [Extraction Process](#extraction-process)
6. [Common Pitfalls](#common-pitfalls)
7. [Available Scripts](#available-scripts)
---
## Overview
The TCBA (Twenty-First Century Baseball Association) website contains extensive historical baseball statistics dating back to 1902. Many pages were originally created using Microsoft Word or Excel, resulting in bloated HTML with Office-specific markup (xmlns:o, xmlns:w, xmlns:m).
### Modernization Goals
- **Reduce file size**: From 800+ lines to 100-300 lines
- **Improve accessibility**: WCAG-compliant contrast, keyboard navigation
- **Enable theming**: Night/Day mode with user preference persistence
- **Ensure responsiveness**: Mobile-friendly layouts
- **Maintain data integrity**: All original content preserved
---
## HTML Structure Standards
### Required DOCTYPE and HTML Tag
```html
```
- Always use `data-theme="night"` as default
- The theme can be toggled by user and persists via localStorage
### Required Meta Tags
```html
TCBA - [Page Title]
]*>.*?["\']>([A-Z][^<\d]+?)\s*\d{4}', content, re.DOTALL | re.IGNORECASE)
```
**Years Range** (handles multiple formats and dash types):
```python
re.search(r'>\s*[-–—]\s*(\d{4}[-–—\d&;ampltp\s]+(?:\d{4}|[Pp]resent))', content)
```
**History Brief** (multi-span text):
```python
re.search(r'History\s*Brief:?\s*(.*?)', content, re.DOTALL | re.IGNORECASE)
```
**Season Records** (table rows with 4-digit year):
```python
if re.match(r'^(19|20)\d{2}$', first_cell_value):
# This is a season record row
```
### modernize_team.py
Generates modern HTML from extracted data and batch processes:
```bash
# Single file
python modernize_team.py TeamName.htm
# Batch process from list
python modernize_team.py --batch team_pages_list.txt
# Force re-process (use -OLD backup as source)
python modernize_team.py --batch team_pages_list.txt --force
```
---
## Common Pitfalls
### 1. Encoding Issues
**Problem**: Windows-1252 characters display as garbled text
**Solution**: Always read with Windows-1252, write with UTF-8
```python
content = Path(filepath).read_text(encoding='windows-1252')
Path(filepath).write_text(html, encoding='utf-8')
```
### 2. Curly Apostrophes in JavaScript
**Problem**: Curly apostrophes (') break JavaScript strings
**Solution**: Use double quotes for strings containing apostrophes
```javascript
// BAD
'Hamilton EH's': 'Hamilton.htm'
// GOOD
"Hamilton EH's": 'Hamilton.htm'
```
### 3. Multi-Span Text Extraction
**Problem**: Text split across multiple `` tags
**Solution**: Capture entire section, then strip ALL tags
```python
# Strip all HTML tags without adding spaces
hist = re.sub(r'<[^>]+>', '', section_text)
hist = re.sub(r'\s+', ' ', hist).strip()
```
### 4. Trailing Dashes in Names
**Problem**: Team names extracted with trailing dashes ("Jersey –")
**Solution**: Strip trailing punctuation
```python
team_name = re.sub(r'\s*[-–—]\s*$', '', team_name).strip()
```
### 5. Season Table Detection
**Problem**: Table headers not consistently formatted
**Solution**: Find rows by detecting 4-digit year in first cell
```python
if values[0] and re.match(r'^(19|20)\d{2}$', values[0]):
# Valid season row
```
---
## Available Scripts
| Script | Purpose | Usage |
|--------|---------|-------|
| `extract_team.py` | Extract data from Word-generated team pages | `python extract_team.py TeamName.htm` |
| `modernize_team.py` | Generate modern HTML from extracted data | `python modernize_team.py --batch` |
| `add_theme_toggle.py` | Add theme toggle to existing modern pages | `python add_theme_toggle.py` |
| `add_back_nav.py` | Add floating back navigation to modern pages | `python add_back_nav.py` |
---
## File Naming Conventions
- **Team pages**: `CityName.htm` or `Nickname.htm` (e.g., `Long Island.htm`, `Scranton.htm`)
- **Backup files**: `OriginalName-OLD.htm` (preserved for data recovery)
- **Modern templates**: Usually same name, overwriting original after backup
- **Stats files**: `Career Batting XX.htm`, `Career Pitching by Team XX.htm` (XX = abbreviation)
---
## Backup Procedure
Before modernizing any file:
1. Create backup with `-OLD` suffix
2. Extract data from original
3. Generate modern HTML
4. Write to original filename
5. Verify extraction was successful
```python
backup_path = filepath.with_name(filepath.stem + '-OLD' + filepath.suffix)
if not backup_path.exists():
shutil.copy(filepath, backup_path)
```
---
## Era Designation System
Teams are tagged with era indicators showing when they played:
| Tag | Era | Color | Hex |
|-----|-----|-------|-----|
| Y | Yesterday | Medium Purple | `#7B68EE` |
| G | Gold | Peru/Tan | `#CD853F` |
| O | Origins | Slate Gray | `#708090` |
| T | Today | Steel Blue | `#4682B4` |
---
## Next Steps
For detailed extraction patterns, see: [EXTRACTION-PROCESS.md](./EXTRACTION-PROCESS.md)
For technical CSS/JS reference, see: [Technical Reference Page](./technical-reference.htm)