---
title: Naomi's Blog
---

Naomi's Blog (hereinafter the "Application") is a personal blog platform built with Next.js that showcases the personal musings of a transfem software engineer. The Application serves markdown-based blog posts with a clean, accessible interface and focuses on storytelling and technical experiences.

## 1. User Documentation

### Overview
Naomi's Blog is a personal blog featuring posts about software engineering, technology, and personal experiences. The blog is accessible at https://blog.nhcarrigan.com and provides a clean, minimalist interface for reading articles.

### Navigation
- **Home Page**: Displays a chronological list of all blog posts with titles, publication dates, and summaries
- **Individual Posts**: Click on any post title to read the full article
- **Return Navigation**: Each post page includes a "← Back to home" link to return to the main listing

### Post Structure
Each blog post includes:
- **Title**: The main heading of the article
- **Publication Date**: Displayed in British format (e.g., "Wednesday, 21 May 2025")
- **Summary**: A brief excerpt visible on the home page
- **Content**: Full markdown-rendered content with support for:
  - Headers and text formatting
  - Links and images
  - Code blocks and syntax highlighting
  - HTML elements when needed

### Accessibility Features
- Semantic HTML structure with proper heading hierarchy
- Underlined links for clear navigation
- Clean typography using Inter font
- Responsive design that works across devices

## 2. Technical Documentation

### Architecture
Naomi's Blog is built using:
- **Framework**: Next.js 15.1.6 with App Router
- **Language**: TypeScript 5.x
- **Styling**: Tailwind CSS with custom CSS variables
- **Content**: Markdown files with frontmatter parsing via gray-matter
- **Markdown Rendering**: react-markdown with rehype-raw and remark-gfm plugins

### Project Structure
```
src/
├── app/
│   ├── layout.tsx          # Root layout with metadata and styling
│   ├── page.tsx            # Home page listing all posts
│   ├── globals.css         # Global styles and CSS variables
│   └── post/[slug]/
│       └── page.tsx        # Dynamic post pages
├── components/
│   └── rule.tsx            # Custom horizontal rule component
└── lib/
    └── posts.ts            # Post data fetching utilities

posts/                      # Markdown blog posts
```

### Installation & Setup
1. **Prerequisites**: Node.js and pnpm package manager
2. **Install dependencies**: `pnpm install`
3. **Development server**: `pnpm dev` (runs on port 3003)
4. **Build for production**: `pnpm build`
5. **Start production server**: `pnpm start`

### Content Management
- **Adding Posts**: Create `.md` files in the `posts/` directory
- **Frontmatter Format**:
  ```yaml
  ---
  title: "Your Post Title"
  date: "YYYY-MM-DD"
  summary: "Brief description of the post"
  ---
  ```
- **Content**: Write in Markdown with GitHub Flavoured Markdown support
- **Automatic Processing**: Posts are automatically sorted by date (newest first)

### Key Features
- **Static Generation**: Posts are processed at build time for optimal performance
- **SEO Optimized**: Proper metadata, Open Graph, and Twitter Card support
- **TypeScript**: Full type safety throughout the application
- **Responsive Design**: Mobile-friendly layout
- **Custom Styling**: Branded colours and typography

## 3. Legal Documentation

### License
The Application is distributed under **Naomi's Public Licence** as indicated in the source code headers.

### Copyright
All source code is copyright © NHCarrigan (Naomi Carrigan).

### Third-Party Dependencies
The Application uses the following open-source libraries:
- **Next.js**: MIT License
- **React**: MIT License  
- **TypeScript**: Apache License 2.0
- **Tailwind CSS**: MIT License
- **gray-matter**: MIT License
- **react-markdown**: MIT License
- **rehype-raw**: MIT License
- **remark-gfm**: MIT License

### Content Policy
Blog post content represents the personal opinions and experiences of the author. Content guidelines and policies specific to this Application may be added here as needed.

## 4. Contributing Documentation

### Development Guidelines
- **Code Style**: ESLint configuration (`@nhcarrigan/eslint-config`) enforces consistent formatting
- **Type Safety**: All code must pass TypeScript checks with no warnings
- **Testing**: Run `pnpm lint` to verify code standards (note: test suite is pending implementation)

### Code Organization
- **Components**: React components go in `src/components/`
- **Utilities**: Helper functions belong in `src/lib/`
- **Pages**: Follow Next.js App Router conventions in `src/app/`
- **Styles**: Global styles in `src/app/globals.css`, component styles via Tailwind classes

### Pull Request Process
1. **Fork & Branch**: Create feature branches from main
2. **Code Quality**: Ensure ESLint passes with zero warnings
3. **Type Safety**: All TypeScript must compile without errors
4. **Documentation**: Update relevant documentation for significant changes
5. **Testing**: Verify the application builds and runs correctly

### File Header Requirements
All source files must include the standard copyright header:
```typescript
/**
 * @copyright NHCarrigan
 * @license Naomi's Public Licence
 * @author Naomi Carrigan
 */
```

### Dependency Management
- Use `pnpm` for package management
- Keep dependencies up to date and security-focused
- Prefer established, well-maintained packages
- Document any new dependencies and their purpose
