juanatsap
16194328b6
## Documentation Updates (doc/11-PDF-EXPORT.md) Added "References Section Integration" section with: - Template code examples for shortcut URL usage - Data configuration structure - Key features and use cases - Security attributes documentation - Test command reference ## Test Updates (tests/mjs/28-references-pdf-download.test.mjs) Completely rewrote test to match new direct link behavior: - ❌ OLD: Tested modal opening, onclick handlers - ✅ NEW: Tests direct shortcut URLs New test coverage (5 tests): 1. English direct shortcut URL validation 2. Spanish direct shortcut URL validation 3. HTTP 301 redirect verification 4. Year validation (404 for invalid years) 5. Works without JavaScript (PDF export context) Verifies: - Correct href: /cv-jamr-{year}-{lang}.pdf - No onclick handlers (pure HTML link) - Security attributes (target="_blank", rel="noopener noreferrer") - Year-aware dynamic URLs - Language-aware (es/en) - Backend 301 redirects working - 404 for past/future years ## Benefits - Comprehensive test coverage for new behavior - Complete documentation with examples - Easy to maintain and understand - Validates entire shortcut URL feature end-to-end
CV Project Documentation
Complete documentation for the Go + HTMX CV website project.
📚 Quick Navigation
For Developers
Getting Started
- 1. Architecture Overview - System design and Go backend architecture
- 2. Modern Web Techniques - Frontend architecture (HTMX, Hyperscript, CSS) ⭐
- 3. API Reference - Complete API documentation with endpoints and responses
Technical Implementation
- 4. Hyperscript Rules - Hyperscript conventions and best practices
- 5. Zoom Implementation - Custom zoom feature technical details
- 12. CSS Architecture - Modular CSS structure and ITCSS organization ⭐
Deployment & Operations
- 8. Deployment Guide - Production deployment instructions
- 9. Security Policies - Security guidelines and vulnerability reporting
For Users & Customizers
- 6. User Guide - End-user documentation for CV features
- 7. Customization Guide - How to customize your CV content and styling
- 10. Privacy Policy - Data handling and privacy information
📖 Documentation Overview
Core Technical Documentation
| # | Document | Purpose | Audience |
|---|---|---|---|
| 1 | ARCHITECTURE.md | Go backend architecture, package structure, design patterns | Backend developers |
| 2 | MODERN-WEB-TECHNIQUES.md | HTMX/Hyperscript frontend architecture, component patterns, ADRs | Frontend developers |
| 3 | API.md | Complete API reference with all endpoints | API consumers, integrators |
| 4 | HYPERSCRIPT-RULES.md | Hyperscript coding conventions | Frontend developers |
| 5 | ZOOM_IMPLEMENTATION.md | Zoom feature implementation details | Feature developers |
| 12 | CSS-ARCHITECTURE.md | Modular CSS structure, ITCSS layers, HTMX integration | Frontend developers, designers |
User & Operations Documentation
| # | Document | Purpose | Audience |
|---|---|---|---|
| 6 | USER_GUIDE.md | End-user feature documentation | CV users |
| 7 | CUSTOMIZATION.md | Content and style customization | CV customizers |
| 8 | DEPLOYMENT.md | Deployment instructions and operations | DevOps, site operators |
| 9 | SECURITY.md | Security policies and reporting | Security teams |
| 10 | PRIVACY.md | Privacy policy and data handling | Legal, compliance |
| 11 | PDF-EXPORT.md | PDF generation architecture and configuration | Backend developers |
🏗️ Architecture Quick Reference
Backend: Go (Hono-inspired routing)
- Clean package structure (
internal/pattern) - Template caching and rendering
- JSON-based CV data model
- Middleware: logging, security headers, CORS
Frontend: HTMX + Hyperscript + Vanilla CSS
- Hypermedia-driven architecture (minimal JavaScript)
- Server-side rendering with HTMX partial updates
- Declarative behaviors with Hyperscript
- Component-level skeleton loaders
- Light/dark/auto color themes
Key Features:
- ✅ Custom zoom control (25%-175%)
- ✅ Bilingual support (English/Spanish)
- ✅ Keyboard shortcuts (L/I/V/?)
- ✅ Print-optimized CSS
- ✅ Mobile responsive
- ✅ Accessibility (WCAG AA compliance)
🎯 Common Tasks
"I want to..."
...understand the system architecture → Start with 1-ARCHITECTURE.md (backend) and 2-MODERN-WEB-TECHNIQUES.md (frontend)
...add a new feature → Read 2-MODERN-WEB-TECHNIQUES.md for frontend patterns, 3-API.md for backend APIs
...customize my CV content → Follow 7-CUSTOMIZATION.md for content and styling changes
...deploy to production → Use 8-DEPLOYMENT.md for step-by-step deployment instructions
...understand HTMX patterns → Check 2-MODERN-WEB-TECHNIQUES.md Section 6 (HTMX Patterns)
...write Hyperscript code → Follow conventions in 4-HYPERSCRIPT-RULES.md
...report a security issue → See 9-SECURITY.md for responsible disclosure process
📦 Archive
Historical documentation (bug fixes, testing reports, implementation notes) is stored in archive/ for reference. These documents are not actively maintained but preserved for historical context.
🔗 External Resources
- HTMX Documentation: https://htmx.org/
- Hyperscript: https://hyperscript.org/
- Go Documentation: https://go.dev/doc/
- Playwright Testing: https://playwright.dev/
📝 Documentation Standards
All documentation in this project follows these standards:
- Markdown format with GitHub-flavored syntax
- Clear structure with table of contents for long documents
- Code examples with syntax highlighting
- Up-to-date reflecting current implementation
- Versioned via Git with meaningful commit messages
Last Updated: 2025-11-20 Documentation Status: ✅ Clean, organized, zero redundancy Total Active Docs: 12 core documents + archive