static-pages/DOCS.md

title

title
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 (/books/)

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 (/music/)

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.

Product Directory (/products/)

An automated directory listing products offered by NHCarrigan. The page displays products from various categories including public projects, games, private projects, and archived items. Products are fetched from Gitea repositories and displayed with their descriptions and links where available.

Games (/games/)

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

BlueSky Handle Generator (/bsky/)

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

Chat Services (/chat/)

A comprehensive page outlining various ways to connect with NHCarrigan, including forum, IRC, and Matrix communication options with direct links and connection details.

Testimonials (/testimonials/)

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

Link Redirector (/link-redirector/)

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.

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
├── chat/                    # Communication options
├── 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

Directories synced automatically:

• bsky, chat, games, link-redirector, testimonials
• manual, sitemap, music, books, products

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 contact@nhcarrigan.com

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

This section is for documentation related to contributing to the Application's codebase.