colin/triqura-ecd
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add release notes page with MDX content system

Browse Source 
Implemented comprehensive release notes feature with:

- MDX-based content system for easy release note authoring
- Thematic sidebar navigation (Foundation, Features, Infrastructure)
- Auto-generated pages from MDX frontmatter
- Overview page with status filtering (completed/in_progress/planned)
- Detail pages with custom MDX components
- Mobile-responsive navigation (horizontal scroll tabs)
- Integration with timeline (link to detailed release notes)
- Added "Releases" link to header navigation

Technical implementation:
- next-mdx-remote for MDX parsing and rendering
- gray-matter for frontmatter extraction
- Custom MDX components for images, code blocks, typography
- Static site generation (SSG) for performance
- Template system for consistent release note structure

Files added:
- app/(marketing)/releases/ - Route structure and components
- content/nl/releases/ - MDX content files and index
- lib/mdx/releases.ts - MDX utility functions
- docs/specs/releasepage/ - Build plan documentation
- docs/templates/release-note-template.mdx - Content template

First release note: authentication.mdx (login, signup, password reset)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
colinislit
2025-11-19 20:59:54 +01:00
parent 501d8de22b
commit 2ae7b37e5f
14 changed files with 2759 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

329
docs/specs/releasepage/bouwplan-release-notes-v1.0.md Normal file
View File

@@ -0,0 +1,329 @@
# 🚀 Bouwplan: Release Notes Feature
**Projectnaam:** Release Notes Pagina
**Versie:** v1.0
**Datum:** 19-11-2024
**Auteur:** Colin + AI
---
## 1. Doel en Context
Toevoegen van een dedicated release notes pagina aan de AI Speedrun website om transparantie te bieden over ontwikkelvoortgang. De pagina past in de "build in public" filosofie en biedt:
- **Overzichtspagina** met lijst van alle releases
- **Detail paginas** per week met uitgebreide release notes
- **Sidebar navigatie** (standard software docs stijl)
- **Links vanuit timeline** naar release details
---
## 2. Uitgangspunten
### 2.1 Technische Stack
- **Frontend:** Next.js 15 (bestaand) + TailwindCSS
- **Content:** MDX bestanden in `/content/nl/releases/` met frontmatter
- **Content Parser:** `next-mdx-remote` of `@next/mdx` voor MDX rendering
- **Routing:** `/releases` (overview) + `/releases/[category]` (detail per functionaliteit)
- **Components:** ReleaseSidebar, MDXContent wrapper
- **Layout:** Marketing layout met sidebar
- **Navigatie:** Thematisch op functionaliteit (niet chronologisch op weken)
- **Images:** `/public/releases/[category]/` voor screenshots en visuals
### 2.2 Projectkaders
- **Tijd:** 2-3 uur implementatie
- **Budget:** €0 (bestaande stack)
- **Scope:** MVP - basis release notes zonder fancy features
- **Design:** Standard docs-stijl (links sidebar + content)
### 2.3 Programmeer Uitgangspunten
- **DRY:** Hergebruik bestaande timeline data waar mogelijk
- **KISS:** Simpele layout, geen onnodige animaties
- **SOC:** Content schemas apart, components herbruikbaar
- **Mobile-first:** Horizontal scroll nav op mobile, sidebar op desktop
---
## 3. Epics & Stories Overzicht
| Epic ID | Titel | Doel | Status | Stories | Geschatte tijd |
|---------|-------|------|--------|---------|----------------|
| E1 | Content Schema | Release data structuur | ⏳ | 2 | 30 min |
| E2 | Route Structure | Pages en layouts | ⏳ | 3 | 45 min |
| E3 | Components | Sidebar + content | ⏳ | 2 | 45 min |
| E4 | Integration | Timeline links + nav | ⏳ | 2 | 30 min |
**Totaal geschat:** 2.5 uur
---
## 4. Epics & Stories (Uitwerking)
### Epic 1 — Content Schema
| Story | Beschrijving | Acceptatie | Status |
|-------|--------------|------------|--------|
| E1.S1 | MDX template maken | Release note template met frontmatter + content secties | ⏳ |
| E1.S2 | Content categories definiëren | Logische indeling functionaliteiten (Auth, Dashboard, AI, etc.) | ⏳ |
| E1.S3 | MDX parser setup | next-mdx-remote configureren voor content rendering | ⏳ |
**MDX Template:**
```mdx
---
title: "Authentication & User Management"
category: "authentication"
group: "foundation"
version: "0.1.0"
releaseDate: "2024-11-15"
status: "completed"
description: "Login, signup en password reset functionaliteit"
---
## Overview
Korte beschrijving van wat er is gebouwd in deze release...
## Features
### Login Flow
![Login screenshot](/releases/authentication/login-screen.png)
Beschrijving van de login functionaliteit:
- Email/password login
- Demo account optie
- Error handling
Code voorbeeld (optioneel):
```tsx
const handleLogin = async (email, password) => {
// implementation
}
```
### Signup Flow
[Details over signup...]
## Technical Notes
- Supabase Auth integratie
- RLS policies voor security
- Client-side validation
## Related Links
- [Timeline Week 1](/timeline#week-1)
- [Database Schema](/docs/schema)
```
**Voorbeeld categorieën:**
- `authentication` - Login, signup, password reset
- `client-management` - CRUD operations voor cliënten
- `dashboard` - EPD dashboard en navigatie
- `ai-features` - AI integraties (samenvatting, classificatie, plannen)
- `infrastructure` - Database, hosting, performance
- `design-system` - UI components en styling
---
### Epic 2 — Route Structure
| Story | Beschrijving | Acceptatie | Status |
|-------|--------------|------------|--------|
| E2.S1 | Layout maken | `app/(marketing)/releases/layout.tsx` met sidebar | ⏳ |
| E2.S2 | Overview page | `app/(marketing)/releases/page.tsx` met lijst (read MDX frontmatter) | ⏳ |
| E2.S3 | Detail pages | `app/(marketing)/releases/[category]/page.tsx` met MDX rendering | ⏳ |
**Structuur:**
```
# Code structuur
app/(marketing)/releases/
├── layout.tsx # Sidebar wrapper
├── page.tsx # Overview (lijst van alle MDX files)
├── [category]/
│ └── page.tsx # MDX content renderer
└── components/
├── release-sidebar.tsx
└── mdx-components.tsx # Custom components voor MDX
# Content structuur
content/nl/releases/
├── authentication.mdx
├── client-management.mdx
├── dashboard.mdx
├── ai-features.mdx
├── infrastructure.mdx
└── design-system.mdx
# Assets structuur
public/releases/
├── authentication/
│ ├── login-screen.png
│ └── signup-flow.png
├── ai-features/
│ ├── summary-demo.gif
│ └── classification.png
└── ...
```
**URL voorbeelden:**
- `/releases` - Overview alle functionaliteiten (parsed MDX frontmatter)
- `/releases/authentication` - Renders `authentication.mdx`
- `/releases/ai-features` - Renders `ai-features.mdx`
- `/releases/dashboard` - Renders `dashboard.mdx`
---
### Epic 3 — Components
| Story | Beschrijving | Acceptatie | Status |
|-------|--------------|------------|--------|
| E3.S1 | ReleaseSidebar | Fixed sidebar desktop, horizontal scroll mobile, reads MDX files | ⏳ |
| E3.S2 | MDX Components | Custom components voor images, code blocks, callouts | ⏳ |
| E3.S3 | Typography styling | Prose styling voor MDX content (tailwindcss/typography) | ⏳ |
**Features:**
- Sidebar auto-generated from MDX files in `/content/nl/releases/`
- Active state in sidebar
- Mobile-responsive
- Status indicators (completed/in progress/planned) from frontmatter
- Custom MDX components:
- Images met caption
- Code blocks met syntax highlighting
- Callout boxes (info, warning, success)
- YouTube/video embeds (optional)
---
### Epic 4 — Integration
| Story | Beschrijving | Acceptatie | Status |
|-------|--------------|------------|--------|
| E4.S1 | Timeline links | "Release notes →" link per week in timeline | ⏳ |
| E4.S2 | Nav menu | "Releases" link in header nav | ⏳ |
**Changes:**
- `timeline.tsx`: Add link per week
- `navigation.json`: Add releases link
- Test navigation flow
---
## 5. Design Specs (Compact)
**Layout:**
```
┌────────────────────────────────────────┐
│ Header (existing) │
├──────────────┬─────────────────────────┤
│ Sidebar │ Main Content │
│ │ │
│ Overview │ # Release Notes │
│ ────── │ │
│ Foundation │ [Category cards...] │
│ ├─ Auth │ │
│ ├─ Database │ │
│ Features │ │
│ ├─ Dashboard │ │
│ ├─ Clients │ │
│ ├─ AI │ │
│ Infrastructure │
│ ├─ Hosting │ │
│ ├─ Design │ │
└──────────────┴─────────────────────────┘
```
**Sidebar structuur (thematisch):**
- **Foundation** (basis setup)
- Authentication
- Database & Schema
- Environment Setup
- **Core Features** (EPD functionaliteit)
- Dashboard & Navigation
- Client Management
- AI Integrations
- **Infrastructure** (ondersteunend)
- Hosting & Deployment
- Design System
- Performance
**Mobile:** Horizontal scroll tabs boven content
**Content styling:**
- `@tailwindcss/typography` plugin voor prose content
- Custom MDX components styled met Tailwind
- Images responsive met captions
- Code blocks met syntax highlighting (shiki/prism)
- Heading anchors voor deep linking
**Colors:**
- Teal accents (consistent met brand)
- Slate backgrounds for code blocks
- White background for main content
- Prose styles voor text readability
---
## 6. Acceptatiecriteria
### Must Have:
- [ ] `/releases` toont overzicht gegroepeerd per categorie
- [ ] `/releases/[category]` toont detail van specifieke functionaliteit
- [ ] Sidebar heeft thematische grouping (Foundation, Features, Infrastructure)
- [ ] Sidebar werkt op desktop (fixed) met collapsible sections
- [ ] Mobile heeft horizontal scroll nav met categorieën
- [ ] Timeline linkt naar relevante release categories
- [ ] "Releases" link in header nav
- [ ] Active states in navigatie
### Nice to Have (later):
- RSS feed
- Search functie
- Filters (features/fixes/improvements)
- Changelog syntax highlighting
---
## 7. Risico's & Mitigatie
| Risico | Kans | Impact | Mitigatie |
|--------|------|--------|-----------|
| Content duplicatie met timeline | Middel | Laag | Hergebruik timeline data, extend met extra fields |
| Mobile nav niet intuïtief | Middel | Middel | Test met gebruiker, voeg tooltips toe indien nodig |
| SEO voor individuele releases | Laag | Laag | Metadata per release page toevoegen |
---
## 8. Implementatie Volgorde
1. **E1.S1:** MDX template maken + voorbeeld content
2. **E1.S2:** Categorieën definiëren (authentication, dashboard, ai-features, etc.)
3. **E1.S3:** MDX parser setup (next-mdx-remote of @next/mdx)
4. **E2.S1:** Layout component met sidebar (thematische grouping)
5. **E3.S1:** ReleaseSidebar component (auto-generated from MDX files)
6. **E3.S2:** Custom MDX components (images, code, callouts)
7. **E3.S3:** Typography styling (@tailwindcss/typography)
8. **E2.S2:** Overview page (list van MDX frontmatter)
9. **E2.S3:** Detail page (MDX renderer)
10. **E4.S1:** Timeline integration (link naar relevante categories)
11. **E4.S2:** Navigation update (releases link)
---
## 9. Referenties
**Bestaande Componenten:**
- `app/(marketing)/components/build-timeline.tsx` - Timeline component
- `content/nl/timeline.json` - Timeline data
- `app/(marketing)/layout.tsx` - Marketing layout
**Design Inspiratie:**
- Next.js docs (https://nextjs.org/docs)
- Vercel changelog (https://vercel.com/changelog)
- Linear releases (https://linear.app/releases)
---
## 10. Versiehistorie
| Versie | Datum | Auteur | Wijziging |
|--------|-------|--------|-----------|
| v1.0 | 19-11-2024 | Colin + AI | Initiële versie - compact bouwplan |
| v1.1 | 19-11-2024 | Colin + AI | Update: thematische indeling ipv chronologisch |
| v1.2 | 19-11-2024 | Colin + AI | Update: MDX/Markdown content ipv JSON/cards |

231
docs/templates/release-note-template.mdx vendored Normal file
View File

@@ -0,0 +1,231 @@
---
title: "[Feature Name] - Descriptive Title"
category: "category-slug"
group: "foundation | features | infrastructure"
version: "0.1.0"
releaseDate: "2024-11-15"
status: "completed | in_progress | planned"
description: "Korte beschrijving (1-2 zinnen) voor overview pagina"
---
## Overview
Korte introductie van wat er is gebouwd. Waarom is dit belangrijk? Welk probleem lost het op?
Bijvoorbeeld:
> "De authentication flow is de basis van het EPD systeem. Gebruikers kunnen nu veilig inloggen, accounts aanmaken en wachtwoorden resetten via Supabase Auth."
---
## Features
### Feature 1: [Naam]
![Screenshot beschrijving](/releases/[category]/[image].png)
*Caption: Beschrijf wat je in de screenshot ziet*
Beschrijving van de feature:
- Belangrijkste functionaliteit
- User benefits
- Edge cases afgehandeld
**Demo:**
- Stap 1: Open `/login`
- Stap 2: Vul credentials in
- Stap 3: Klik op login knop
- Resultaat: Redirect naar `/epd/clients`
**Code voorbeeld** (optioneel):
```tsx
// Relevante code snippet
const handleLogin = async (email: string, password: string) => {
const { data, error } = await supabase.auth.signInWithPassword({
email,
password
})
if (error) throw error
return data
}
```
### Feature 2: [Naam]
[Herhaal bovenstaande structuur...]
---
## Improvements
Verbeteringen aan bestaande functionaliteit:
- **Performance:** Login response tijd van 2s naar 500ms
- **UX:** Error messages nu user-friendly
- **Accessibility:** Keyboard navigation toegevoegd
---
## Bug Fixes
Opgeloste bugs (indien van toepassing):
- ✅ Fixed: Wachtwoord reset email kwam niet aan
- ✅ Fixed: Session expiry handling
- ✅ Fixed: Redirect loop bij logout
---
## Technical Notes
### Architecture
Technische details voor developers:
- **Stack:** Supabase Auth + Next.js 15 + Server Actions
- **Database:** RLS policies voor user isolation
- **Security:** PKCE flow voor OAuth
- **Session:** JWT tokens in httpOnly cookies
### File Structure
```
app/
├── login/
│ └── page.tsx # Login form
├── signup/
│ └── page.tsx # Signup form
└── auth/
└── callback/
└── route.ts # OAuth callback handler
lib/
├── auth/
│ ├── client.ts # Client-side auth functions
│ └── server.ts # Server-side auth helpers
```
### Database Schema
```sql
-- Relevant tables/policies
CREATE POLICY "Users can only read own data"
ON profiles FOR SELECT
USING (auth.uid() = id);
```
### Configuration
Environment variables vereist:
```bash
NEXT_PUBLIC_SUPABASE_URL=your_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_key
```
---
## Breaking Changes
⚠️ **Let op:** Breaking changes voor developers (indien van toepassing):
- `loginUser()` functie hernoemd naar `signInWithPassword()`
- `UserSession` type nu `Session` (import van @supabase/supabase-js)
**Migration guide:**
```tsx
// ❌ Oud
import { loginUser } from '@/lib/auth'
const session = await loginUser(email, password)
// ✅ Nieuw
import { signInWithPassword } from '@/lib/auth/client'
const { data } = await signInWithPassword(email, password)
```
---
## Testing
### Manual Test Checklist
- [ ] Login met valid credentials werkt
- [ ] Login met invalid credentials toont error
- [ ] Signup flow compleet doorlopen
- [ ] Password reset email ontvangen
- [ ] Session persists na page reload
- [ ] Logout werkt correct
### Automated Tests
```bash
# Run tests
npm run test:auth
# Coverage
npm run test:coverage
```
---
## Metrics
**Development:**
- ⏱️ Build tijd: 8 uur
- 📝 Lines of code: ~450
- 🧪 Test coverage: 85%
**Performance:**
- 🚀 Login response: < 500ms (was 2s)
- 📦 Bundle size: +12kb (auth client)
- 💾 Database queries: 2 per login
**Cost:**
- 💰 Supabase: €0 (free tier)
- 💰 Vercel: €0 (hobby plan)
---
## Screenshots
### Login Screen
![Login screen](/releases/authentication/login-screen.png)
*Login formulier met email/password en demo account optie*
### Signup Flow
![Signup screen](/releases/authentication/signup-flow.png)
*Signup formulier met password confirmation*
### Error States
![Error handling](/releases/authentication/error-states.png)
*User-friendly error messages voor verschillende scenarios*
---
## Related Links
**Timeline:**
- [Week 1 - Foundation](/timeline#week-1)
**Documentation:**
- [Database Schema](/docs/database-schema)
- [API Documentation](/docs/api)
**External:**
- [Supabase Auth Docs](https://supabase.com/docs/guides/auth)
- [Next.js Auth Guide](https://nextjs.org/docs/authentication)
---
## What's Next
Geplande verbeteringen voor volgende releases:
- 🔜 OAuth providers (Google, GitHub)
- 🔜 Multi-factor authentication (MFA)
- 🔜 Magic link login
- 🔜 Session management dashboard
---
## Feedback
Vragen of feedback? [Open een issue](https://github.com/[org]/[repo]/issues) of [stuur een email](mailto:contact@example.com).