# Migration Guide: Old System → New Architecture

## What Changed

### Old System
```
index.php (PHP logic mixed with HTML)
  └─ Hardcoded sidebar generation
  └─ JavaScript fetches JSON files
  └─ HTML partials scattered in directories
  └─ build.nu generates *.json files
```

### New System
```
index.php (simple entry point)
  └─ router.php (request handling)
  └─ template.php (base layout)
  └─ lib/ContentRenderer.php (markdown → HTML)
  └─ lib/ContentManager.php (content discovery)
  └─ content/ (all markdown files)
  └─ partials/ (footer, sidebar, etc.)
  └─ js/enhance.js (progressive enhancement)
```

## Benefits

1. **Server-side rendering** - Full HTML sent to browser
   - ✅ Better SEO
   - ✅ Works without JavaScript
   - ✅ Better accessibility
   - ✅ No flash of unstyled content

2. **Cleaner separation** - Each file has one responsibility
   - ✅ Router handles URLs
   - ✅ ContentManager finds content
   - ✅ ContentRenderer converts markdown
   - ✅ Template handles layout

3. **Easier to extend**
   - ✅ Add new sections just by creating `content/section/index.md`
   - ✅ Add blog posts just by creating `content/blog/post.md`
   - ✅ No build step needed!

4. **Better caching** - Optional file-based caching included
   - ✅ Enable in ContentRenderer constructor
   - ✅ Automatic invalidation
   - ✅ Perfect for high-traffic sites

## Migration Checklist

### Already Done ✓
- [x] Created `lib/ContentRenderer.php` - Markdown rendering
- [x] Created `lib/ContentManager.php` - Content discovery
- [x] Created `router.php` - Request routing
- [x] Created `template.php` - Base layout
- [x] Created `partials/sidebar.php` - Navigation
- [x] Created `partials/footer.php` - Footer
- [x] Created `js/enhance.js` - Progressive enhancement
- [x] Created `.htaccess` - URL rewriting
- [x] Created `content/` directory structure
- [x] Copied all markdown files to `content/`

### Manual Steps

1. **Test the new system:**
   ```bash
   # Visit in browser
   http://your-site/
   http://your-site/blog
   http://your-site/blog/htmz
   ```

2. **Update any custom partials:**
   - If you have special wasm.html, copy it to `partials/wasm.html`
   - Any other includes should go in `partials/`

3. **Remove old files (after testing):**
   ```bash
   # Backup first!
   cp -r /home/jisifu/public_html /home/jisifu/public_html.backup
   
   # Then remove old files
   rm index.php.old  # (old index.php)
   rm home/*.json
   rm blog/*.json
   rm about/*.json
   # etc
   ```

4. **Update build.nu (optional):**
   The build process is now simpler. You only need:
   ```nushell
   # Just validate/verify your markdown files exist
   glob content/**/*.md | print
   ```

## How It Works

### Request Flow

1. **Browser requests `/blog`**
2. **Apache redirects to `/router.php` via .htaccess**
3. **router.php**:
   - Parses the path (`/blog`)
   - Calls `ContentManager::getSection('blog')` or `getBlogPosts()`
   - Passes content to `ContentRenderer`
   - Includes `template.php`
4. **template.php**:
   - Renders full HTML page
   - Includes `enhance.js`
5. **enhance.js** (in browser):
   - Attaches click handlers to sidebar links
   - On click: Fetches page via AJAX, updates DOM, updates URL

### No JavaScript?
- Content still loads! The `<a href="/blog">` links work
- Full page reloads instead of smooth transitions
- This is progressive enhancement

## File Structure Reference

```
public_html/
├── index.php              ← Entry point (new: just includes router)
├── router.php             ← NEW: Request routing
├── template.php           ← NEW: Base layout
├── .htaccess              ← NEW: URL rewriting
│
├── lib/
│   ├── ContentRenderer.php     ← NEW: Markdown → HTML
│   └── ContentManager.php      ← NEW: Content discovery
│
├── partials/              ← NEW: Layout components
│   ├── sidebar.php
│   ├── footer.php
│   └── wasm.html          (optional)
│
├── js/
│   └── enhance.js         ← NEW: Progressive enhancement
│
├── content/               ← NEW: All markdown files
│   ├── home/index.md
│   ├── blog/
│   │   ├── post1.md
│   │   └── post2.md
│   ├── projects/index.md
│   └── ...
│
├── home/                  ← OLD: Can be archived/deleted
├── blog/                  ← OLD: Can be archived/deleted
├── cache/                 ← NEW: Optional caching directory
│
└── ... (existing assets)
```

## Adding Content

### Add a New Section
```bash
# Create content file
echo "# My New Section" > content/newsection/index.md
echo "This is my content" >> content/newsection/index.md

# Done! Visit http://site/newsection
```

### Add a Blog Post
```bash
# Create markdown file
echo "# My Blog Post" > content/blog/my-post.md
echo "Here's the content..." >> content/blog/my-post.md

# Done! Visit http://site/blog/my-post
```

No build step needed!

## Caching (Optional)

To enable automatic caching:

```php
// In router.php, change:
$renderer = new ContentRenderer($use_file_cache = true);  // Enable caching

// Cache will be stored in cache/ directory
```

To clear cache:
```php
// Call this when you update content
$renderer->clearCache();
```

## Troubleshooting

### "404 Not Found" on new pages
- Check that `.htaccess` is enabled (ask your host)
- Verify `content/section/index.md` exists
- Check PHP error log

### JavaScript not working smoothly
- Check browser console for errors
- Verify `js/enhance.js` is loading
- Try without JavaScript (should still work)

### Old index.php still showing
- Clear browser cache
- Check that new `index.php` was updated
- Restart web server if needed

## Performance Tips

1. **Enable caching** for high-traffic sites:
   ```php
   $renderer = new ContentRenderer(true);
   ```

2. **Minify CSS/JS** at the envs.net level (already done)

3. **Use browser caching** - `.htaccess` is already configured

4. **Preload pages** - `enhance.js` preloads on hover (already enabled)

## Next Steps

1. Test thoroughly in a staging environment
2. Backup before removing old files
3. Monitor error logs for issues
4. Update any deployment scripts to reference `content/` directory

## Questions?

Refer to `ARCHITECTURE.md` for design details or check the code comments.