# guangzhengli/nextjs-blog-template architecture

> Architecture diagram of the GitHub repository guangzhengli/nextjs-blog-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guangzhengli/nextjs-blog-template
- Repository: https://github.com/guangzhengli/nextjs-blog-template

## Overview

##### Main Components
- Next.js Application: At the core, the project uses Next.js (with the new app directory structure) to manage routing and server-side rendering.
- Routing & Pages (src/app): Includes the main pages such as homepage, blog listing (src/app/blog/page.tsx), blog details (src/app/blog/[...slug]/page.tsx), and error routes (not-found.tsx, robots.ts, sitemap.ts).
- Content (src/content): Markdown and MDX files are stored under src/content/blog. These files represent the actual blog posts and are integrated into the application.
- Configuration & Utilities (src/lib): Contains centralized configuration (src/lib/config.ts) for site settings (SEO, social links, author info, etc.) along with utility functions (src/lib/toc.ts, src/lib/utils.ts).
- Hooks (src/hooks): Custom React hooks (e.g., use-mounted.ts) which likely enhance component behavior.
- Build & Deployment Scripts (scripts and public): The scripts directory includes custom scripts (generate-rss.js and generate-sitemap.js) for generating RSS feeds and sitemaps. The public directory holds assets and the generated feeds (atom.xml, feed.json, rss.xml, site.webmanifest).
- Tooling & Configuration: Files like tsconfig.json, eslint.config.mjs, package.json, next.config.ts, and postcss.config.mjs indicate TypeScript use, linting rules, and build configuration that support the overall project architecture.

##### Relationships and Interactions
- User/Browser: Interacts with the Next.js frontend.
- Frontend (app pages and UI components): Dynamically fetches and renders content (markdown/mdx) from the src/content directory and applies the configurations from src/lib/config.ts.
- Components and Hooks: UI components interact with custom hooks and utilities to provide interactive behavior and consistent layout.
- Build Scripts: Scripts (under scripts/) run during build/deployment to generate essential assets (RSS feeds, sitemaps) and are triggered by package.json commands (npm run generate-rss, npm run generate-sitemap).
- External Services: Integration with Giscus for comments and configuration for social media links (github, twitter, etc.) as set in config.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Code is organized according to functionality—routing (src/app), UI (src/components), content (src/content), configuration (src/lib).
- Modularization: Reusable components and utilities help maintain clarity and ease of updates.
- Convention over Configuration: Leveraging Next.js app directory conventions, standardized naming, and centralized configuration (src/lib/config.ts).
- Server-Side Rendering & Static Optimization: Next.js handles both dynamic and static content, as seen in the pages and build scripts.
- Extensibility: Clear separation between core functionality and configurations allow easy extensions and theming.

## Diagram (Mermaid)

```mermaid
graph TD
    Browser["User/Browser"]:::external

    %% Next.js Frontend Layer
    subgraph "Next.js Frontend"
        App["Next.js Application"]:::framework
        %% Routing & Pages Sub-layer
        subgraph "Routing & Pages"
            BL["Blog Listing Page"]:::routing
            BD["Blog Details Page"]:::routing
            NF["Not Found Page"]:::routing
            RB["Robots Page"]:::routing
            SM["Sitemap Page"]:::routing
        end
        %% UI Components & Layout Sub-layer
        subgraph "UI Components & Layout"
            Header["Header"]:::ui
            Icons["Icons"]:::ui
            UIButton["UI Elements"]:::ui
            MDX["MDX Components"]:::ui
        end
        Hooks["Custom Hooks"]:::hooks
        useMounted["useMounted Hook"]:::hooks
    end

    %% Content Management Layer
    Content["Content Management"]:::content
    BlogPosts["Blog Posts"]:::content

    %% Configuration & Utilities Layer
    Configs["Configuration & Utilities"]:::config
    Config["Config"]:::config
    TOC["TOC Utility"]:::config
    Utils["Utils"]:::config

    %% Build & Deployment Layer
    Build["Build & Deployment Scripts"]:::build
    generateRSS["generate-rss"]:::build
    generateSitemap["generate-sitemap"]:::build
    PublicAssets["Public Assets"]:::public

    %% Tooling & Infrastructure Layer
    Tools["Tooling & Infrastructure"]:::tools
    TSConfig["tsconfig"]:::tools
    NextConfig["Next.js Config"]:::tools
    ESLint["ESLint Config"]:::tools
    PostCSS["PostCSS Config"]:::tools
    Package["Package.json"]:::tools

    %% External Services
    External["External Services (Giscus, Social Links)"]:::external

    %% Relationships
    Browser -->|"request"| App
    App -->|"routes"| BL
    App -->|"routes"| BD
    App -->|"routes"| NF
    App -->|"routes"| RB
    App -->|"routes"| SM
    App -->|"composes"| Header
    App -->|"composes"| Icons
    App -->|"composes"| UIButton
    App -->|"composes"| MDX

    Header -->|"utilizes"| Hooks
    Icons -->|"utilizes"| Hooks
    UIButton -->|"utilizes"| Hooks
    MDX -->|"utilizes"| Hooks
    Hooks -->|"includes"| useMounted

    BL -->|"fetches content"| BlogPosts
    BD -->|"fetches content"| BlogPosts
    BL -->|"fetches config"| Configs
    BD -->|"fetches config"| Configs
    Header -->|"fetches config"| Configs

    Configs -->|"contains"| Config
    Configs -->|"contains"| TOC
    Configs -->|"contains"| Utils

    Build -->|"executes"| generateRSS
    Build -->|"executes"| generateSitemap
    generateRSS -->|"outputs"| PublicAssets
    generateSitemap -->|"outputs"| PublicAssets

    Tools -->|"supports"| App

    Config -->|"integrates"| External

%% Click Events
click App "https://github.com/guangzhengli/nextjs-blog-template/tree/main/src/app"
click BL "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/app/blog/page.tsx"
click BD "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/app/blog/[...slug]/page.tsx"
click NF "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/app/not-found.tsx"
click RB "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/app/robots.ts"
click SM "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/app/sitemap.ts"
click Header "https://github.com/guangzhengli/nextjs-blog-template/tree/main/src/components/header"
click Icons "https://github.com/guangzhengli/nextjs-blog-template/tree/main/src/components/icons"
click UIButton "https://github.com/guangzhengli/nextjs-blog-template/tree/main/src/components/ui"
click MDX "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/components/mdx-components.tsx"
click Content "https://github.com/guangzhengli/nextjs-blog-template/tree/main/src/content"
click BlogPosts "https://github.com/guangzhengli/nextjs-blog-template/tree/main/src/content/blog"
click Config "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/lib/config.ts"
click TOC "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/lib/toc.ts"
click Utils "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/lib/utils.ts"
click Hooks "https://github.com/guangzhengli/nextjs-blog-template/tree/main/src/hooks"
click useMounted "https://github.com/guangzhengli/nextjs-blog-template/blob/main/src/hooks/use-mounted.ts"
click Build "https://github.com/guangzhengli/nextjs-blog-template/tree/main/scripts"
click generateRSS "https://github.com/guangzhengli/nextjs-blog-template/blob/main/scripts/generate-rss.js"
click generateSitemap "https://github.com/guangzhengli/nextjs-blog-template/blob/main/scripts/generate-sitemap.js"
click PublicAssets "https://github.com/guangzhengli/nextjs-blog-template/tree/main/public"
click TSConfig "https://github.com/guangzhengli/nextjs-blog-template/blob/main/tsconfig.json"
click NextConfig "https://github.com/guangzhengli/nextjs-blog-template/blob/main/next.config.ts"
click ESLint "https://github.com/guangzhengli/nextjs-blog-template/blob/main/eslint.config.mjs"
click PostCSS "https://github.com/guangzhengli/nextjs-blog-template/blob/main/postcss.config.mjs"
click Package "https://github.com/guangzhengli/nextjs-blog-template/blob/main/package.json"

%% Styles
classDef external fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
classDef framework fill:#aed6f1,stroke:#3498db,stroke-width:2px;
classDef routing fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
classDef ui fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
classDef hooks fill:#fdebd0,stroke:#f39c12,stroke-width:2px;
classDef content fill:#d6eaf8,stroke:#5dade2,stroke-width:2px;
classDef config fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
classDef build fill:#fadbd8,stroke:#e67e22,stroke-width:2px;
classDef public fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
classDef tools fill:#d5dbdb,stroke:#7f8c8d,stroke-width:2px;
```
