Skip to content
NHCarrigan Logo NHCarrigan Docs

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.

  • 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: 
    ---
    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 colors and typography

License

The Application is distributed under Naomi’s Public License as indicated in the source code headers.

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:

/**
 * @copyright nhcarrigan
 * @license Naomi's Public License
 * @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