docs/src/content/docs/projects/website-headers.md

title

title
Website Headers

Website Headers (hereinafter the "Application") is a JavaScript/TypeScript library that injects standardised metadata, styles, and UI components (such as footers and modals) into web pages. It is designed to provide consistent branding, accessibility, and legal compliance for Naomi Carrigan's web properties. The Application dynamically adds Open Graph and Twitter meta tags, favicons, global styles, a themed footer, analytics scripts, and a community call-to-action modal. It also supports theme toggling and audio playback for enhanced user experience.

1. User Documentation

What does this library do?

The Website Headers library automatically enhances any webpage by injecting:

• SEO metadata: Open Graph and Twitter Card meta tags for better social media sharing
• Favicons: Complete set of favicon files for various devices and platforms
• Global styling: Consistent branding with OpenDyslexic font, custom cursor, and themed UI
• Footer component: Standardized footer with copyright, social links, theme toggle, and donation button
• Analytics: Plausible Analytics integration with event tracking
• Community features: Periodic modal popup encouraging users to join the community
• Theme support: Light/dark theme toggle with localStorage persistence
• Audio controls: Optional theme music playback
• TreeNation integration: Carbon offset widget display

Features

• Accessibility-focused: Uses OpenDyslexic font for improved readability
• Responsive design: Mobile-friendly layout with adaptive footer
• Theme persistence: Remembers user's theme preference across sessions
• Privacy-respecting: Uses privacy-focused Plausible Analytics
• Performance optimised: Minified production build with deferred script loading
• Cross-platform: Works on all modern browsers and devices

Integration

Simply include the library script in your HTML:

<script src="https://cdn.nhcarrigan.com/website-headers.js"></script>

The library will automatically enhance your page with all the features listed above.

2. Technical Documentation

Prerequisites

• Node.js (latest LTS version recommended)
• pnpm package manager
• TypeScript knowledge for development

Installation

1. Clone the repository:

   git clone <repository-url>
   cd website-headers
   

2. Install dependencies:

   pnpm install
   

Development

Local Development Server

To work on the library locally with hot reloading:

pnpm dev

This command:

• Compiles TypeScript to JavaScript in watch mode
• Starts a development server on port 8080
• Serves a test HTML page at http://localhost:8080
• Automatically updates when you make changes

Building for Production

pnpm build

This command:

• Runs ESLint for code quality checks
• Compiles TypeScript to JavaScript
• Minifies the output using Terser
• Injects the current version number
• Outputs the final file to prod/index.js

Code Quality

pnpm lint

Runs ESLint with strict configuration to ensure code quality.

Project Structure

src/
├── index.ts      # Main library code
└── develop.ts    # Development server

prod/
├── index.js      # Production build output
└── develop.js    # Development server build

build.ts          # Build script with minification
index.html        # Test page for development
package.json      # Project configuration
tsconfig.json     # TypeScript configuration
eslint.config.js  # ESLint configuration

Architecture

The library is structured as a single TypeScript file that:

1. Metadata Injection: Dynamically creates and injects meta tags for SEO and social sharing
2. Asset Loading: Loads external resources (fonts, scripts, stylesheets)
3. Component Creation: Builds UI components (footer, modal) and injects them into the DOM
4. Event Handling: Sets up interactive features (theme toggle, audio player, modal)
5. State Management: Manages theme preferences and modal display timing using localStorage

Key Components

• Meta Tags: Open Graph and Twitter Card metadata
• Favicon Management: Complete favicon set for all platforms
• Global Styles: CSS-in-JS for consistent theming
• Footer Component: Branded footer with interactive elements
• Modal System: Community CTA with timing-based display logic
• Theme System: Light/dark mode with system preference detection
• Analytics Integration: Privacy-focused event tracking

External Dependencies

The library loads several external resources:

• OpenDyslexic font for accessibility
• Font Awesome icons for UI elements
• Plausible Analytics for privacy-respecting tracking
• TreeNation widget for carbon offset display
• Google AdSense for monetization

Environment Variables

• npm_package_version: Automatically injected during build process

3. Legal Documentation

Licensing

This software is licensed under Naomi's Public Licence.

Copyright Notice: Copyright held by Naomi Carrigan.

Third-Party Services

The Application integrates with several third-party services that have their own terms of service and privacy policies:

Analytics and Tracking

• Plausible Analytics: Privacy-focused web analytics
  • Domain: analytics.nhcarrigan.com
  • Data collected: Page views, events, referrers (no personal data)
  • Privacy policy: Plausible Privacy Policy

Advertising

• Google AdSense: Contextual advertising platform
  • Client ID: ca-pub-3569924701890974
  • May collect user data for ad personalisation
  • Privacy policy: Google Privacy Policy

Environmental Impact

• TreeNation: Carbon offset and environmental impact tracking
  • Widget code: a17464e0cd351220
  • Purpose: Display environmental impact metrics
  • Privacy policy: TreeNation Privacy Policy

Content Delivery

• NHCarrigan CDN: Custom content delivery network
  • Domain: cdn.nhcarrigan.com
  • Hosts: fonts, images, audio files, cursors
  • Subject to NHCarrigan privacy policies

Data Collection and Privacy

Local Storage Usage

The Application stores the following data in the user's browser:

• theme: User's preferred colour scheme (light/dark)
• naomi-community-cta: Timestamp of last community modal display

External Resource Loading

The Application loads resources from external domains:

• Font files from cdn.nhcarrigan.com
• Analytics scripts from analytics.nhcarrigan.com
• Advertising scripts from googlesyndication.com
• Icons from Font Awesome CDN

Compliance Considerations

Organizations using this library should be aware that it:

• Loads third-party tracking scripts
• May be subject to GDPR, CCPA, and other privacy regulations
• Includes advertising components that may require disclosure
• Collects analytics data that may need privacy policy updates

Contact Information

For legal inquiries regarding this Application:

• Email: contact@nhcarrigan.com
• Community: Chat Server

4. Contributing Documentation

Getting Started

We welcome contributions to the website-headers project! Please review our contributing guidelines and Code of Conduct before getting started.

Development Workflow

1. Fork the repository and clone your fork locally
2. Create a new branch for your feature or bug fix:

   git checkout -b feature/your-feature-name
   

3. Install dependencies:

   pnpm install
   

4. Start the development server:

   pnpm dev
   

5. Make your changes and test them at http://localhost:8080
6. Run linting to ensure code quality:

   pnpm lint
   

7. Build for production to verify everything works:

   pnpm build
   

8. Commit your changes and push to your fork
9. Create a Pull Request with a clear description of your changes

Code Style and Standards

• TypeScript: All code must be written in TypeScript
• ESLint: Code must pass all linting rules (@nhcarrigan/eslint-config)
• No warnings: Build process fails if ESLint warnings are present
• Comments: Use JSDoc comments for functions and complex logic
• Accessibility: Maintain accessibility features (fonts, colours, ARIA labels)

Testing

• Manual Testing: Use the development server to test changes
• Cross-browser: Test in multiple browsers when possible
• Mobile Responsive: Verify changes work on mobile devices
• Theme Testing: Test both light and dark themes

Areas for Contribution

High Priority

• Performance optimisation: Reduce bundle size, optimise loading
• Accessibility improvements: Enhanced ARIA support, keyboard navigation
• Mobile experience: Better responsive design, touch interactions
• Browser compatibility: Support for older browsers

Medium Priority

• Documentation: Improve inline code documentation
• Error handling: Add graceful fallbacks for external resource failures
• Testing framework: Implement automated testing
• Configuration options: Make the library more customisable

Low Priority

• Additional themes: More colour scheme options
• Animation effects: Subtle transitions and animations
• Internationalization: Multi-language support
• Advanced analytics: More detailed event tracking

Pull Request Guidelines

• Clear title: Descriptive title explaining the change
• Detailed description: Explain what changes were made and why
• Screenshots: Include before/after screenshots for UI changes
• Testing notes: Describe how you tested the changes
• Breaking changes: Clearly mark any breaking changes
• Version impact: Indicate if this should be a major, minor, or patch release

Code Review Process

1. Automated checks: ESLint and build checks must pass
2. Manual review: Code will be reviewed for quality and functionality
3. Testing: Changes will be tested in various environments
4. Feedback: You may be asked to make additional changes
5. Merge: Once approved, changes will be merged to main branch

Release Process

• Semantic versioning: We follow semver (major.minor.patch)
• Automated builds: Successful merges trigger automated builds
• CDN deployment: Production builds are deployed to CDN
• Documentation updates: Documentation is updated with releases

Getting Help

• Issues: Post in the #bug-reports or #feature-requests forum channels on our Discord community
• Discussions: Use Gitea discussions for questions and ideas
• Community: Join our chat server for real-time help
• Email: Contact us at contact@nhcarrigan.com for private inquiries

Recognition

Contributors will be recognised in:

• Git commit history
• Release notes
• Project documentation
• Community acknowledgments