---
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:

```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:
   ```bash
   git clone <repository-url>
   cd website-headers
   ```

2. Install dependencies:
   ```bash
   pnpm install
   ```

### Development

#### Local Development Server

To work on the library locally with hot reloading:

```bash
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

```bash
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

```bash
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](https://docs.nhcarrigan.com/legal/license).

**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](https://plausible.io/privacy)

#### Advertising
- **Google AdSense**: Contextual advertising platform
  - Client ID: `ca-pub-3569924701890974`
  - May collect user data for ad personalisation
  - Privacy policy: [Google Privacy Policy](https://policies.google.com/privacy)

#### Environmental Impact
- **TreeNation**: Carbon offset and environmental impact tracking
  - Widget code: `a17464e0cd351220`
  - Purpose: Display environmental impact metrics
  - Privacy policy: [TreeNation Privacy Policy](https://tree-nation.com/privacy)

#### 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](https://chat.nhcarrigan.com)

## 4. Contributing Documentation

### Getting Started

We welcome contributions to the website-headers project! Please review our [contributing guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) 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:
   ```bash
   git checkout -b feature/your-feature-name
   ```
3. **Install dependencies**:
   ```bash
   pnpm install
   ```
4. **Start the development server**:
   ```bash
   pnpm dev
   ```
5. **Make your changes** and test them at `http://localhost:8080`
6. **Run linting** to ensure code quality:
   ```bash
   pnpm lint
   ```
7. **Build for production** to verify everything works:
   ```bash
   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](https://chat.nhcarrigan.com) 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