---
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 and legal/compliance links 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 with persisted preference.

## 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 custom fonts, 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
- **TreeNation integration**: Carbon offset widget display

### Features

- **Accessibility-focused**: High-contrast theming and semantic metadata support
- **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

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

The `prod/` directory is generated during build output and is not a permanent source directory.

### 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, social panel, 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:
- Google-hosted font assets used by the injected stylesheet
- 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/#/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, scripts, and 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
