nhcarrigan/docs
9
0
Fork 0
generated from nhcarrigan/template
Code Issues 2 Pull Requests 6 Actions Releases 1 Activity
Files
8398dcdf5eec5530fcc6619e90c1b6d7eb4b172b
docs/src/content/docs/projects/static-pages.md
T
naomi f8748b828a feat: document all the fings
2025-10-29 17:36:56 -07:00

17 KiB
Raw Blame History

title
title
Static Pages

Static Pages (hereinafter the "Application") is a collection of static HTML pages that serve as the foundation for various web-based services and informational resources offered by Naomi Carrigan. The Application provides a lightweight, accessible platform for showcasing personal content, accepting donations, displaying testimonials, cataloguing personal collections, and managing product information.

1. User Documentation

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

1.1 Available Pages

The Application consists of several distinct pages, each serving a specific purpose:

1.1.1 Donation Page (/donate)

The donation page provides multiple avenues for supporting Naomi Carrigan's work, including:

  • OpenCollective: Main financial ledger tracking all income and expenses
  • Patreon: Monthly membership support
  • Ko-Fi: Coffee donations and one-time contributions
  • PayPal: Direct donation processing
  • CashApp: Direct monetary transfers
  • GitHub Sponsors: Platform-integrated sponsorship
  • Stripe: Monthly recurring donations
  • Twitch: Stream subscriptions
  • Throne: Gift suggestion and purchase platform
  • Discord: Community hub access

1.1.2 Book Library (/books)

An interactive explorer displaying books that Naomi has read. Features include:

  • Searchable database by author and title
  • Filterable results with dynamic count display
  • Alphabetically sorted table view
  • JSON-backed data storage (books.json)
  • Currently displays over 1,000 books

1.1.3 Music Library (/music)

An interactive explorer for music that Naomi listens to. Features include:

  • Search functionality for artists and titles
  • Dynamic filtering with live count updates
  • Tabular display with alternating row colors
  • JSON-backed data storage (songs.json)

1.1.4 Testimonials (/testimonials)

A comprehensive showcase of professional feedback and recommendations from:

  • Past clients
  • Colleagues
  • Community members
  • Internal team feedback (anonymized for privacy)

Features include:

  • Print-optimized styling
  • Chronologically organized testimonials
  • Web form integration for new submissions
  • Over 50 professional testimonials spanning multiple years (2023-2025)

1.1.5 Link Redirector (/link-redirector)

A fallback page for improperly configured subdomain redirects, providing users with support contact information.

1.1.6 Additional Pages

  • Chat (/chat): Community communication hub
  • Mail (/mail): Email-related services
  • Games (/games): Gaming-related content
  • Manual (/manual): User manuals and guides
  • Sitemap (/sitemap): Site navigation structure
  • Bluesky (/bsky): Bluesky social platform integration

1.2 Common Features

All pages share common functionality through a global header system:

  • Consistent styling via CSS custom properties (variables)
  • Responsive design for mobile and desktop
  • Global navigation (loaded from cdn.nhcarrigan.com/headers/index.js)
  • Consistent theming with foreground/background color variables
  • Custom cursor styles

1.3 Accessibility

The Application is designed with accessibility in mind:

  • Semantic HTML5 structure
  • Proper heading hierarchy
  • Descriptive page titles and meta descriptions
  • Responsive viewport scaling
  • UTF-8 character encoding

2. Technical Documentation

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

2.1 Architecture

The Application is a pure static website with no backend dependencies:

  • Technology Stack: HTML5, CSS3, Vanilla JavaScript
  • Data Storage: JSON files for dynamic content
  • Styling: Custom CSS with CSS custom properties
  • Scripts: Vanilla JavaScript (no frameworks)
  • CDN Dependencies: Global header/navigation system from cdn.nhcarrigan.com

2.2 File Structure

static-pages/
├── books/
│   ├── index.html
│   └── books.json
├── music/
│   ├── index.html
│   └── songs.json
├── testimonials/
│   └── index.html
├── donate/
│   └── index.html
├── products/
│   ├── index.html
│   └── data.json
├── link-redirector/
│   └── index.html
├── bsky/
├── chat/
├── games/
├── mail/
├── manual/
├── sitemap/
├── README.md
├── CONTRIBUTING.md
├── LICENSE.md
├── PRIVACY.md
├── TERMS.md
├── SECURITY.md
└── CODE_OF_CONDUCT.md

2.3 Dependencies

2.3.1 External Dependencies

  • Global Header System: https://cdn.nhcarrigan.com/headers/index.js
    • Provides consistent navigation and styling across all pages
    • Loaded asynchronously with defer attribute
  • Font Awesome: Icon library (loaded via global header)
  • Custom Cursors: https://cdn.nhcarrigan.com/cursors/pointer.cur

2.3.2 Internal Dependencies

  • JSON data files for dynamic content (books.json, songs.json, data.json)

2.4 Deployment

The Application can be deployed to any static web host:

2.4.1 Prerequisites

  • Web server capable of serving static files (Nginx, Apache, etc.)
  • No server-side processing required
  • No database required

2.4.2 Installation Steps

  1. Clone the repository:

    git clone <repository-url>
cd static-pages

  2. Configure your web server to serve the directory:

    • Set document root to the static-pages directory
    • Configure directory indexing if needed
    • Ensure proper MIME types are set for .html, .json, .css files

  3. (Optional) Update the global header CDN URL if hosting independently:

    • Replace cdn.nhcarrigan.com/headers/index.js with your own header script
    • Update custom cursor URLs if needed

2.4.3 Web Server Configuration

Nginx Example:

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/static-pages;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~* \.(json)$ {
        add_header Content-Type application/json;
    }
}

Apache Example (.htaccess):

DirectoryIndex index.html
Options -Indexes
<Files ~ "\\.json$">
    Header set Content-Type "application/json"
</Files>

2.5 Data Management

2.5.1 Books Library

Run ./books.sh to update the book data. You may need to change the filepath the script reads from.

2.5.2 Music Library

Run ./songs.sh to update the music data. You may need to change the filepath the script reads from.

2.5.3 Testimonials List

Run ./testimonials.sh to update the testimonial data from our API.

2.6 Customization

2.6.1 Styling

Each page uses CSS custom properties that can be overridden:

  • --foreground: Primary foreground color
  • --background: Primary background color

Global styles are loaded from the CDN header system. To customize:

  1. Fork and host your own version of the header script
  2. Update the script src in each HTML file
  3. Modify CSS custom properties in your hosted version

2.6.2 Adding New Pages

  1. Create a new directory in the root
  2. Add an index.html file
  3. Include the global header script: 
    <script
  src="https://cdn.nhcarrigan.com/headers/index.js"
  async
  defer
></script>
  4. Follow the existing HTML structure for consistency

2.7 System Requirements

Client-Side:

  • Modern web browser with JavaScript enabled
  • Support for ES6+ JavaScript features
  • Support for CSS custom properties

Server-Side:

  • Any static file web server (Nginx, Apache, Caddy, etc.)
  • No specific server-side language requirements
  • No database requirements

2.8 Version Control

The Application is managed using Git:

2.9 Continuous Integration

CI/CD configuration files are located in .gitea/workflows/:

  • sonar.yml: SonarQube code quality analysis

3. Legal Documentation

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

3.1 License

The Application is licensed under the global software license maintained by Naomi Carrigan. Full license details are available at:

3.2 Privacy Policy

User privacy is governed by the global privacy policy:

  • URL: https://docs.nhcarrigan.com/#/privacy
  • Reference: See PRIVACY.md in the repository root
  • Data Collection: The Application itself does not collect user data; however, external links may have their own privacy policies

3.3 Terms of Service

Usage of the Application is subject to the global terms of service:

3.4 Security Policy

Security-related information and vulnerability reporting:

  • Reference: See SECURITY.md in the repository root
  • Contact: For security concerns, contact via the official channels listed in the security policy

3.5 Third-Party Services

The Application integrates with several third-party services:

3.5.1 Donation Platforms

  • OpenCollective
  • Patreon
  • Ko-Fi
  • PayPal
  • CashApp
  • GitHub Sponsors
  • Stripe
  • Twitch
  • Throne
  • Discord

Each platform has its own terms of service and privacy policy that users should review before proceeding with transactions.

3.5.2 Content Delivery Network (CDN)

  • Service: cdn.nhcarrigan.com
  • Purpose: Global header, navigation, and styling
  • Data Handling: Standard CDN caching and delivery

3.6 User Responsibilities

Users of the Application agree to:

  • Use the Application for lawful purposes only
  • Respect intellectual property rights
  • Not attempt to exploit, hack, or compromise the Application's security
  • Follow the Code of Conduct when interacting with the community

3.7 Data Portability

All user-facing data in the Application is stored in JSON format and can be easily exported or migrated:

  • Books data: books/books.json
  • Music data: music/songs.json
  • Products data: products/data.json

4. Contributing Documentation

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

4.1 Getting Started

To contribute to the Application:

  1. Read the Contributing Guidelines:

  2. Review the Code of Conduct:

    • See CODE_OF_CONDUCT.md in the repository root
    • Violations can be reported through official channels

  3. Set Up Development Environment:

    # Clone the repository
git clone <repository-url>
cd static-pages

# No build tools required - edit HTML files directly
# Use any text editor or IDE

4.2 Contribution Workflow

  1. Fork the Repository:

    • Fork on Gitea or GitHub
    • Clone your fork locally

  2. Create a Feature Branch:

    git checkout -b feature/your-feature-name

  3. Make Your Changes:

    • Edit HTML, CSS, or JSON files as needed
    • Test locally by opening HTML files in a browser
    • Ensure consistent styling and structure

  4. Commit Your Changes:

    git add .
git commit -m "feat: description of your changes"

  5. Push to Your Fork:

    git push origin feature/your-feature-name

  6. Open a Pull Request:

    • Navigate to the original repository
    • Click "New Pull Request"
    • Fill out the pull request template in .gitea/pull_request_template.yml

4.3 Coding Standards

4.3.1 HTML Standards

  • Use HTML5 semantic elements
  • Include proper DOCTYPE declaration
  • Set UTF-8 charset
  • Include viewport meta tag for responsive design
  • Use descriptive page titles and meta descriptions

4.3.2 CSS Standards

  • Use CSS custom properties for theming
  • Maintain responsive design principles
  • Use consistent class naming conventions
  • Include print styles where appropriate
  • Test cross-browser compatibility

4.3.3 JavaScript Standards

  • Use vanilla JavaScript (no frameworks)
  • Follow ES6+ standards
  • Use const/let instead of var
  • Include error handling where appropriate
  • Keep functions small and focused
  • Comment complex logic

4.3.4 JSON Data Standards

  • Maintain consistent schema within each data file
  • Use proper JSON formatting (validated)
  • Include all required fields
  • Use descriptive keys

4.4 Testing

Before submitting a pull request:

  1. Manual Testing:

    • Open each modified HTML file in multiple browsers
    • Test on both desktop and mobile viewports
    • Verify all links work correctly
    • Ensure JSON data loads properly

  2. Validation:

    • Validate HTML using W3C validator
    • Validate JSON syntax using a JSON validator
    • Check CSS for syntax errors

  3. Cross-Browser Testing:

    • Test in Chrome/Chromium
    • Test in Firefox
    • Test in Safari (if available)
    • Test in Edge

4.5 Issue Reporting

Use the issue templates in .gitea/issue_template/:

4.5.1 Bug Reports

  • Template: bug_report.yaml
  • Include reproduction steps
  • Provide browser and OS information
  • Include screenshots if applicable

4.5.2 Feature Proposals

  • Template: feature_proposal.yml
  • Describe the feature clearly
  • Explain the use case
  • Consider implementation impact

4.5.3 Other Issues

  • Template: other.yml
  • For general inquiries or discussions

4.6 Pull Request Guidelines

  • Fill out the pull request template completely
  • Reference related issues using #issue-number
  • Keep changes focused on a single feature or fix
  • Update documentation if needed
  • Respond to review feedback promptly
  • Ensure CI checks pass (if applicable)

4.7 Communication Channels

4.8 Areas for Contribution

4.8.1 High Priority

  • Accessibility improvements
  • Cross-browser compatibility fixes
  • Performance optimizations
  • Documentation updates

4.8.2 Medium Priority

  • New page additions
  • Enhanced filtering/search features
  • Visual design improvements
  • Mobile experience enhancements

4.8.3 Low Priority

  • Additional data entries (books, music, etc.)
  • Minor styling tweaks
  • Code refactoring

4.9 Recognition

Contributors are recognized through:

  • Git commit history
  • Pull request acknowledgments
  • Potential testimonial features for significant contributions

4.10 Development Tools

Recommended tools for contributing:

  • Editors: VS Code, Sublime Text, Atom, or any text editor
  • Browser DevTools: Chrome DevTools, Firefox Developer Tools
  • Validators: W3C HTML Validator, JSONLint
  • Version Control: Git (command line or GUI)

4.11 Local Development

To run locally:

  1. Simple HTTP Server (Python):

    python -m http.server 8000
# Visit http://localhost:8000

  2. Simple HTTP Server (Node.js):

    npx http-server -p 8000
# Visit http://localhost:8000

  3. VS Code Live Server Extension:

    • Install Live Server extension
    • Right-click HTML file → "Open with Live Server"

4.12 Commit Message Guidelines

Follow conventional commit format:

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • style: Code formatting (no logic changes)
  • refactor: Code refactoring
  • test: Test additions or updates
  • chore: Build process or tooling changes

Example:

feat: add search functionality to testimonials page

- Implement client-side search filtering
- Add search input with clear button
- Update styling for search controls

Appendix A: Page-Specific Technical Details

Books Page

  • Data Source: books/books.json
  • JavaScript Functions:
    • loadBooks(books): Initializes the book list
    • filterBooks(author, title): Filters books by author and/or title
    • updateTable(books): Renders the book table
  • Current Count: 1,210 books

Music Page

  • Data Source: music/songs.json
  • JavaScript Functions:
    • loadSongs(songs): Initializes the song list
    • filterSongs(artist, title): Filters songs by artist and/or title
    • updateTable(songs): Renders the song table

Products Page

  • Data Source: products/data.json
  • JavaScript Functions:
    • loadProducts(products): Processes and displays products by category
    • titleCase(name): Converts kebab-case to Title Case
  • Categories: public, private, games, archived
  • Current Count: ~50 products

Testimonials Page

  • Data Format: Static HTML cards generated from source
  • Styling Features:
    • Screen-optimized and print-optimized views
    • Responsive card layout
    • Chronological ordering
  • Submission: Via web form at https://forms.nhcarrigan.com/form/M_GrmqASymmO744axMOmu2LaMAaT5F0LmdVcU2c8-gQ

Document Version: 1.0 Last Updated: 2025-10-29 Maintained By: Naomi Carrigan Contact: contact@nhcarrigan.com

Reference in New Issue View Git Blame Copy Permalink