Skip to content

Commit 1434a3f

Browse files
jaapbrasserjaapbrasser
committed
Added readme / architecture overview
1 parent dc129e6 commit 1434a3f

File tree

3 files changed

+267
-1
lines changed

3 files changed

+267
-1
lines changed

‎README.md‎

Lines changed: 107 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,107 @@
1-
# DuPSUGSite
1+
# Dutch PowerShell User Group Website
2+
3+
This repository contains the source code for the **Dutch PowerShell User Group (DuPSUG)** website.
4+
The site provides information about upcoming events, blog posts, and resources for the PowerShell and automation community in the Netherlands.
5+
6+
---
7+
8+
## 🚀 Tech Stack
9+
10+
**Frontend Framework & Runtime**
11+
- [Next.js 14](https://nextjs.org/) – React framework with App Router for static export and file-based routing
12+
- [React 18](https://react.dev/) – UI library with concurrent features and hooks
13+
- [TypeScript](https://www.typescriptlang.org/) – Type-safe JavaScript for a better developer experience
14+
15+
**Styling & UI**
16+
- [Tailwind CSS](https://tailwindcss.com/) – Utility-first CSS framework
17+
18+
**Hosting**
19+
- [GitHub Pages](https://pages.github.com/) – Static site hosting
20+
21+
---
22+
23+
## 📝 Adding Blog Posts
24+
Blog posts are written in Markdown and live in the `data/blog/` directory.
25+
Each post must include a frontmatter header:
26+
27+
```markdown
28+
---
29+
title: "DuPSUG – Autumn 2025 🍂"
30+
date: "2025-09-23"
31+
author: "Admin"
32+
---
33+
```
34+
35+
title → Title of the blog post
36+
37+
date → Publication date in YYYY-MM-DD format
38+
39+
author → Post author (defaults to Admin if omitted)
40+
41+
To add a new blog post, copy an existing file in data/blog/ and adjust the header and content.
42+
43+
## 🔄 Deployment
44+
Deployment is handled automatically with GitHub Actions.
45+
46+
* Push changes to main
47+
* GitHub Actions will build and export the site to docs/
48+
* GitHub Pages serves the site from the docs/ folder on the main branch
49+
50+
The deployed site is available at:
51+
👉 https://dupsug.github.io/dupsugsite
52+
53+
```
54+
┌────────────┐ ┌────────────────┐ ┌───────────────────┐
55+
│ Commit │ --> │ GitHub Actions │ --> │ GitHub Pages (docs│
56+
│ to main │ │ build & export│ │ branch folder) │
57+
└────────────┘ └────────────────┘ └───────────────────┘
58+
```
59+
60+
## 🐞 Troubleshooting
61+
404s or missing CSS
62+
Make sure basePath and assetPrefix in next.config.mjs match the repository name (/dupsugsite).
63+
64+
GitHub Actions build errors
65+
Check workflow logs under .github/workflows/nextjs.yml.
66+
67+
Blog post not rendering
68+
Verify frontmatter header matches the required format.
69+
70+
## 🤝 Contributing
71+
Contributions from the PowerShell community are welcome!
72+
If you’d like to add content or improve the site:
73+
74+
* Fork the repo
75+
* Create a feature branch
76+
* Open a pull request
77+
78+
## 🛠 Local Development
79+
80+
Clone the repository and install dependencies:
81+
82+
```bash
83+
git clone https://github.com/DuPSUG/dupsugsite.git
84+
cd dupsugsite
85+
npm install
86+
```
87+
88+
Start the development server:
89+
90+
```bash
91+
Copy code
92+
npm run dev
93+
```
94+
The site will be available at http://localhost:3000.
95+
96+
## 📦 Build & Export
97+
This project uses Next.js static export.
98+
99+
```bash
100+
Copy code
101+
npm run build
102+
```
103+
104+
By default, static files are output to the docs/ directory for deployment to GitHub Pages.
105+
106+
## 📄 License
107+
This project is licensed under the MIT License.

‎architecture.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
## Technology Overview & Architecture Analysis
2+
3+
Based on my analysis of the DuPSUG website codebase, here's a comprehensive overview of the technologies used and their interdependencies:
4+
5+
### Core Technology Stack
6+
7+
**Frontend Framework & Runtime:**
8+
- **Next.js 14** - React framework with App Router for server-side rendering and file-based routing
9+
- **React 18** - UI library with concurrent features and hooks
10+
- **TypeScript** - Type-safe JavaScript for better development experience
11+
12+
**Styling & UI:**
13+
- **Tailwind CSS** - Utility-first CSS framework for rapid UI development
14+
- **Radix UI** - Headless component library providing 20+ accessible components
15+
- **Geist Font** - Modern typography system (Sans & Mono variants)
16+
- **Tailwind Typography** - Plugin for beautiful markdown rendering
17+
18+
**State Management:**
19+
- **React Context** - Custom providers for text size and theme management
20+
- **next-themes** - Theme switching functionality (light/dark mode)
21+
- **localStorage** - Persistent storage for user preferences
22+
23+
**Data Processing:**
24+
- **Gray Matter** - Frontmatter parsing for markdown files
25+
- **Marked** - Markdown to HTML conversion with custom renderer
26+
- **Remark** - Additional markdown processing utilities
27+
28+
**Development & Build Tools:**
29+
- **PostCSS & Autoprefixer** - CSS processing and vendor prefixing
30+
- **ESLint** - Code linting and quality assurance
31+
- **GitHub Actions** - CI/CD pipeline for automated deployment
32+
33+
### Architecture Diagram
34+
35+
```mermaid
36+
graph TB
37+
%% Data Sources
38+
DS[Data Sources]
39+
MD[Markdown Files<br/>/data/blog/*.md]
40+
FS[File System<br/>Node.js fs/promises]
41+
LS[localStorage<br/>User Preferences]
42+
43+
%% Server Components
44+
SC[Server Components]
45+
Layout[app/layout.tsx<br/>Root Layout Provider]
46+
Page[app/page.tsx<br/>Home Page]
47+
PostsLib[lib/posts.server.ts<br/>Data Processing]
48+
49+
%% Client Components
50+
CC[Client Components]
51+
Header[TerminalHeader<br/>Navigation & Branding]
52+
BlogList[BlogListClient<br/>Post List & Pagination]
53+
BlogPost[BlogPost<br/>Individual Post Display]
54+
MarkdownRenderer[MarkdownRenderer<br/>Content Processing]
55+
TextSizeProvider[TextSizeProvider<br/>Font Size Context]
56+
TextSizeManager[TextSizeManager<br/>Size Controls]
57+
ThemeProvider[ThemeProvider<br/>Theme Context]
58+
59+
%% UI Components
60+
UI[UI Components<br/>Radix UI]
61+
Cards[Card Components]
62+
Buttons[Button Components]
63+
Forms[Form Components]
64+
65+
%% External Services
66+
ES[External Services]
67+
Vercel[Vercel Analytics<br/>Usage Tracking]
68+
Fonts[Geist Fonts<br/>Typography]
69+
70+
%% Dependencies Flow
71+
DS -->|Raw Content| PostsLib
72+
FS -->|File Operations| PostsLib
73+
PostsLib -->|Processed Posts| Page
74+
LS -->|User Settings| TextSizeProvider
75+
LS -->|Theme Settings| ThemeProvider
76+
77+
%% Server to Client Flow
78+
Page -->|Server Rendered| Layout
79+
Layout -->|Providers| TextSizeProvider
80+
Layout -->|Providers| ThemeProvider
81+
TextSizeProvider -->|Context| TextSizeManager
82+
ThemeProvider -->|Context| Header
83+
84+
%% Component Hierarchy
85+
Page -->|Initial Data| BlogList
86+
BlogList -->|Post Data| BlogPost
87+
BlogPost -->|Content| MarkdownRenderer
88+
MarkdownRenderer -->|HTML| UI
89+
90+
%% Styling Flow
91+
Tailwind[Tailwind CSS<br/>Utility Classes] -->|Styles| Header
92+
Tailwind -->|Styles| BlogList
93+
Tailwind -->|Styles| BlogPost
94+
Tailwind -->|Styles| UI
95+
96+
%% External Integrations
97+
Vercel -->|Analytics| Page
98+
Fonts -->|Typography| Layout
99+
100+
%% Build Process
101+
NextJS[Next.js Build<br/>SSR + Static Gen] -->|Optimized| Page
102+
GitHubActions[GitHub Actions<br/>CI/CD] -->|Deploy| Vercel
103+
104+
%% Subgraph for Data Processing
105+
subgraph "Data Processing Pipeline"
106+
MD -->|Read| PostsLib
107+
PostsLib -->|Parse Frontmatter| GrayMatter[Gray Matter]
108+
PostsLib -->|Convert MD to HTML| Marked[Marked Renderer]
109+
GrayMatter -->|Metadata| PostsLib
110+
Marked -->|HTML Content| PostsLib
111+
end
112+
113+
%% Subgraph for State Management
114+
subgraph "State Management"
115+
TextSizeProvider -->|Context API| TextSizeManager
116+
ThemeProvider -->|Context API| Header
117+
TextSizeManager -->|UI Controls| UI
118+
end
119+
120+
%% Subgraph for UI Layer
121+
subgraph "UI Component Layer"
122+
UI -->|Primitives| Cards
123+
UI -->|Primitives| Buttons
124+
UI -->|Primitives| Forms
125+
Cards -->|Composition| BlogPost
126+
Buttons -->|Composition| Header
127+
end
128+
```
129+
130+
### Key Dependencies & Data Flow
131+
132+
**Data Sources → Processing Pipeline:**
133+
1. **Markdown Files** (`/data/blog/*.md`) contain blog posts with frontmatter metadata
134+
2. **File System** operations read these files using Node.js `fs/promises`
135+
3. **Gray Matter** parses frontmatter (title, date, author, tags, excerpt)
136+
4. **Marked** converts markdown content to HTML with custom renderer
137+
5. **Posts Library** (`lib/posts.server.ts`) orchestrates the entire data processing pipeline
138+
139+
**Server-Side Rendering Flow:**
140+
1. **Page Component** (`app/page.tsx`) fetches posts using `getBlogPosts()`
141+
2. **Server Components** render initial HTML with post data
142+
3. **Client Components** hydrate for interactivity (blog list, theme switching)
143+
144+
**State Management Architecture:**
145+
1. **TextSizeProvider** manages font size preferences via React Context
146+
2. **ThemeProvider** handles light/dark theme switching
147+
3. **localStorage** persists user preferences across sessions
148+
4. **Context Consumers** throughout the app access and update these states
149+
150+
**UI Component Architecture:**
151+
1. **Radix UI** provides headless, accessible component primitives
152+
2. **Custom Components** compose these primitives with Tailwind styling
153+
3. **Terminal-themed Design** creates a unique developer-focused aesthetic
154+
155+
**Build & Deployment:**
156+
1. **Next.js** handles SSR, static generation, and optimization
157+
2. **GitHub Actions** automates build and deployment to Vercel
158+
3. **Vercel Analytics** provides usage insights
159+
160+
This architecture creates a modern, performant blog platform with excellent developer experience, accessibility, and user customization options.

‎public/img_1758715320889.png‎

494 KB
Loading

0 commit comments

Comments
 (0)