Documentation System

Overview

• 📝 Makkelijk te schrijven (Markdown/MDX)
• 🎨 Rich content support (images, code, links)
• 🗂️ Thematische organisatie (niet chronologisch)
• 📱 Mobile-first responsive design
• ⚡ Performance (Static Site Generation)
• 🔍 SEO-vriendelijk met metadata per release

Features

MDX Content System

---
title: "Feature Name"
category: "feature-slug"
group: "foundation | features | infrastructure"
version: "0.1.0"
releaseDate: "2024-11-19"
status: "completed | in_progress | planned"
description: "Short description"
---

## Overview
Content here...

• Markdown syntax = makkelijk schrijven
• Frontmatter voor metadata
• MDX = React components in content mogelijk
• Version control via Git
• Automatische parsing en rendering

Thematische Sidebar Navigatie

• Foundation - Basis setup (Auth, Database, Environment)
• Core Features - EPD functionaliteit (Dashboard, Clients, AI)
• Infrastructure - Ondersteunend (Hosting, Design, Performance)

• Collapsible sections per group
• Status indicators (completed/in progress/planned)
• Active state highlighting
• Auto-generated from MDX files

Overview Page

• ✅ Voltooid - Afgeronde features
• 🔄 In Progress - Features in ontwikkeling
• ⏳ Gepland - Toekomstige features

• Aantal voltooide releases
• Aantal in-progress releases
• Aantal geplande releases

Detail Pages

• Rich MDX rendering
• Custom styled components
• Code syntax highlighting
• Responsive images met captions
• SEO metadata per page
• Navigation (terug naar overview, naar timeline)

Mobile Responsive

• Fixed sidebar (256px width)
• Full content area
• Collapsible groups

• Horizontal scroll tabs boven content
• Touch-friendly navigation
• Optimized voor kleine schermen

Custom MDX Components

• Headings (h1-h4) met spacing
• Paragraphs met optimale line-height
• Lists (ordered/unordered)
• Blockquotes met teal accent

• Images met captions en responsive sizing
• Code blocks met syntax highlighting
• Tables met styled headers

• Internal links (Next.js Link)
• External links met proper attributes
• Teal color scheme (consistent met brand)

Technical Notes

Architecture

• Next.js 15 App Router
• next-mdx-remote voor MDX rendering
• gray-matter voor frontmatter parsing
• TypeScript voor type safety

• Server-side MDX parsing
• Static Site Generation (SSG)
• Pre-rendered HTML voor performance
• Client-side hydration

File Structure

# Code
app/(marketing)/documentatie/
├── layout.tsx              # Sidebar wrapper
├── page.tsx               # Overview
├── [category]/
│   └── page.tsx           # Detail renderer
└── components/
    ├── release-sidebar.tsx
    └── mdx-components.tsx

# Content
content/nl/documentatie/
├── _index.json            # Categories metadata
├── authentication.mdx
└── release-notes-system.mdx

# Utilities
lib/mdx/
└── releases.ts            # MDX parsing functions

# Templates
docs/templates/
└── release-note-template.mdx

Key Functions

// Get all release notes
export async function getAllReleases(): Promise<ReleaseNote[]> {
  const files = fs.readdirSync(RELEASES_DIR)
  // Parse MDX files, extract frontmatter
  // Sort by group and category
  return releases
}

// Get single release by slug
export async function getRelease(slug: string): Promise<ReleaseNote | null> {
  const filePath = path.join(RELEASES_DIR, `${slug}.mdx`)
  const { data, content } = matter(fileContent)
  return { slug, frontmatter: data, content }
}

Static Site Generation

// Generate static params for all releases
export async function generateStaticParams() {
  const releases = await getAllReleases()
  return releases.map((release) => ({
    category: release.slug,
  }))
}

• Pre-rendered HTML = snelle load times
• No runtime MDX parsing = beter performance
• SEO-friendly = search engines kunnen content lezen

Improvements

• Template bestand voor consistente structuur
• TypeScript types voor frontmatter
• Auto-completion in VS Code (frontmatter schema)

• Responsive design voor alle devices
• Snelle navigatie met sidebar
• Clear visual hierarchy
• Status badges voor transparency

• Static generation = < 100ms load time
• Optimized images (Next.js Image)
• Minimal JavaScript bundle (+12kb voor MDX parser)

Workflow

Nieuwe Release Note Toevoegen

cp docs/templates/release-note-template.mdx \
   content/nl/documentatie/new-feature.mdx

---
title: "New Feature Name"
category: "new-feature"
group: "features"
version: "0.3.0"
releaseDate: "2024-11-20"
status: "completed"
description: "Short description here"
---

mkdir -p public/documentatie/new-feature/
# Add images: screenshot-1.png, etc.

npm run build
npm run dev
# Visit /documentatie/new-feature

git add content/nl/documentatie/new-feature.mdx
git commit -m "docs: add new-feature release note"

Integration

Timeline Integration

<a href="/documentatie">
  Bekijk gedetailleerde release notes →
</a>

Navigation Integration

{
  "links": [
    { "label": "Releases", "href": "/documentatie" },
    { "label": "Contact", "href": "/contact" },
    { "label": "Login", "href": "/login" }
  ]
}

Metrics

• ⏱️ Build tijd: 2.5 uur
• 📝 Lines of code: ~2,750
• 🧪 Build status: ✅ Success

• 🚀 Page load: < 100ms (static)
• 📦 Bundle size: +12kb (MDX parser)
• 💾 Build time: +2.2s (22 static pages)

• 14 new files
• 6 components
• 3 utility functions
• 2 documentation files
• 1 template file

• 💰 Dependencies: €0 (open source)
• 💰 Hosting: €0 (Vercel static)
• 💰 Build time: €0 (within limits)

Screenshots

Overview Page

Sidebar Navigation

Detail Page

Mobile View

Related Links

• Bouwplan v1.2
• Release Note Template

• Build Timeline - Week overzicht

• next-mdx-remote
• gray-matter
• MDX Documentation

What's Next

• 🔜 RSS feed voor release notes
• 🔜 Search functionaliteit
• 🔜 Filters (features/fixes/improvements)
• 🔜 Changelog syntax highlighting
• 🔜 Email notifications bij nieuwe releases
• 🔜 Automatic changelog generation from git commits
• 🔜 Dark mode support
• 🔜 Export naar PDF/Markdown

Lessons Learned

• MDX = perfecte balans tussen eenvoud en kracht
• Thematische indeling > chronologische indeling
• Template systeem zorgt voor consistentie
• Static generation = excellent performance

• Syntax highlighting library toevoegen (shiki/prism)
• Table of contents auto-generation
• Reading time estimation
• Related releases suggestions

• MDX parsing utilities
• Release sidebar component
• Custom MDX components
• Template structure