Static Pages

Static Pages (hereinafter the “Application”) is a collection of static HTML pages and related data/scripts for various small web utilities and content sections. The application provides interactive explorers for books and music libraries, product directories, games, chat services, testimonials, and other utility pages. It is designed to be easily synchronized to a production server using shell scripts and requires no backend or dynamic server-side logic.

1. User Documentation

The Application provides several interactive web utilities:

Book Library

Visit at https://books.nhcarrigan.com

An interactive explorer for Naomi’s book collection. Users can browse and search through the library of books with filtering capabilities by author. The interface displays book titles and authors extracted from digital book files.

Music Library

Visit at https://music.nhcarrigan.com

An interactive explorer for Naomi’s music collection. Similar to the book library, users can browse and search through songs with filtering by artist. The interface displays song titles and artists extracted from audio file metadata.

Games

Visit at https://games.nhcarrigan.com

A landing page showcasing various games developed by NHCarrigan, including links to the Beccalia Series and other game projects.

BlueSky Handle Generator

Visit at https://naomi.party

A service page for provisioning custom Bluesky handles under the naomi.party domain. Currently requires manual processing through the Discord support server.

Testimonials

Visit at https://testimonials.nhcarrigan.com

A showcase page displaying testimonials from past clients about NHCarrigan’s work and services.

Link Redirector

Visit at https://nhcarrigan.link

A utility page that serves as a fallback for improperly configured subdomain redirects, providing users with support contact information.

This section is for those interacting with a live instance of the Application.

User Manual

Visit at https://manual.nhcarrigan.com

A brief description of what it is like to work with Naomi, and how to cultivate an environment where she can thrive.

2. Technical Documentation

System Requirements

• Unix-like operating system (Linux/macOS)
• Bash shell
• rsync for deployment
• exiftool for extracting book metadata
• mid3v2 for extracting music metadata
• jq for JSON processing
• Access to Gitea API (for products functionality)
• Web server capable of serving static files

Project Structure

├── books/                    # Book library interface
│   ├── index.html           # Main book explorer page
│   └── books.json           # Generated book data
├── music/                   # Music library interface
│   ├── index.html           # Main music explorer page
│   └── songs.json           # Generated music data
├── products/                # Product directory
│   ├── index.html           # Product listing page
│   └── data.json            # Generated product data
├── games/                   # Games showcase
├── bsky/                    # BlueSky handle service
├── testimonials/            # Client testimonials
├── link-redirector/         # Redirect fallback
├── mail/                    # Mail service (manual sync)
├── manual/                  # Manual/documentation
├── sitemap/                 # Site navigation
├── books.sh                 # Book data generator script
├── songs.sh                 # Music data generator script
├── products.sh              # Product data generator script
└── sync.sh                  # Deployment script

Data Generation Scripts

Book Library (books.sh)

• Scans /home/naomi/cloud/Books directory for book files
• Extracts title and author metadata using exiftool
• Generates books/books.json with book data
• Handles files without metadata by using filenames

Music Library (songs.sh)

• Scans /home/naomi/music directory for audio files
• Extracts title and artist metadata using mid3v2
• Generates music/songs.json with song data
• Falls back to filename parsing for missing metadata

Product Directory (products.sh)

• Fetches repository data from Gitea API
• Organizes projects by category (public, games, private, archived)
• Generates products/data.json with project information
• Requires GITEA_TOKEN environment variable

Deployment

The deployment process uses sync.sh which:

1. Syncs all directories to production server using rsync
2. Targets prod:/home/nhcarrigan for most content
3. Requires manual sync for mail/index.html to mail:/home/user-data/www/default

Deployment Command:

./sync.sh

Running Your Own Instance

1. Clone the repository

2. Install dependencies:

   # Ubuntu/Debian
   sudo apt install exiftool python3-mutagen jq rsync
   
   # macOS
   brew install exiftool jq rsync
   pip3 install mutagen

3. Configure data sources:

   • Update paths in books.sh for your book collection
   • Update paths in songs.sh for your music collection
   • Set GITEA_TOKEN environment variable for products functionality
   • Modify products.sh with your Gitea instance URL and organizations

4. Generate data:

   ./books.sh      # Generate book library data
   ./songs.sh      # Generate music library data
   ./products.sh   # Generate product directory data

5. Serve static files:

   # Simple Python server for testing
   python3 -m http.server 8000

6. Deploy to production:

   • Modify sync.sh with your server details
   • Ensure SSH key authentication is configured
   • Run ./sync.sh

This section is for those interested in running their own instance of the Application.

3. Legal Documentation

The Application operates under NHCarrigan’s standard legal framework:

License

This software is licensed under the global software license. Copyright is held by Naomi Carrigan.

Privacy Policy

Privacy considerations for the Application are covered under the global privacy policy.

Terms of Service

Terms of service for the Application are outlined in TERMS.md.

Code of Conduct

All interactions with the Application’s community and codebase are governed by the Code of Conduct, referenced in CODE_OF_CONDUCT.md.

Security Policy

Security reporting and handling procedures are documented in SECURITY.md.

Data Handling

• Book Library: Processes local book file metadata only
• Music Library: Processes local music file metadata only
• Product Directory: Fetches public repository information from Gitea API
• BlueSky Service: Collects handle requests through Discord (manual process)
• No personal data: The Application does not collect or store personal user data directly

This section is for expansions to our legal policies specific to the Application.

4. Contributing Documentation

Getting Started

Contributors should review the global contributing guidelines referenced in CONTRIBUTING.md.

Development Workflow

1. Fork and Clone

   git clone https://github.com/your-username/Static Pages.git
   cd Static Pages

2. Set Up Development Environment

   • Install required dependencies (see Technical Documentation)
   • Configure data source paths for testing
   • Set up environment variables if working with products functionality

3. Making Changes

   • HTML Pages: Edit individual index.html files in respective directories
   • Data Scripts: Modify *.sh scripts for data generation logic
   • Deployment: Update sync.sh for deployment configuration changes

4. Testing Changes

   # Test data generation
   ./books.sh
   ./songs.sh
   ./products.sh
   
   # Test locally
   python3 -m http.server 8000

5. Submitting Changes

   • Create feature branch: git checkout -b feature/your-feature
   • Commit changes with descriptive messages
   • Push to your fork and create a Pull Request
   • Ensure all data generation scripts work correctly

Code Style Guidelines

• HTML: Use semantic HTML5 elements, include proper meta tags
• Shell Scripts: Follow bash best practices, include error handling
• JSON Data: Ensure proper formatting and validation
• Documentation: Update relevant documentation for new features

Areas for Contribution

• UI/UX Improvements: Enhance styling and user experience of static pages
• Data Processing: Improve metadata extraction and data generation scripts
• New Features: Add new utility pages or improve existing functionality
• Documentation: Expand user guides and technical documentation
• Testing: Add validation and testing for data generation processes
• Accessibility: Improve accessibility compliance across all pages

Communication

• Issues: Report bugs and request features through GitHub Issues
• Support: Join the chat server for discussion
• Contact: Reach out via email at [email protected]

Review Process

All Pull Requests are reviewed for:

• Code quality and adherence to project standards
• Functionality and testing
• Documentation updates
• Security considerations
• Compatibility with existing deployment process