How btholt/next-course-starter works
Project Type and Purpose
• This is a Next.js–based static-site generator tailored for educational courses. It reads Markdown lessons, course metadata (course.json & meta.json), and frontmatter, then uses Next.js’s SSG (getStaticProps / getStaticPaths) to build a fully client-hydrated React site. It also provides build-time utilities (CSV generation, ChatGPT-powered SEO metadata) and a GitHub Actions workflow for deployment to GitHub Pages.
High-Level File-Structure Analysis
• “context/”: React Context providers for global state (course info, header data).
• “pages/”: Next.js page files, incl. dynamic routes under pages/lessons/[section]/[slug].js, plus _app.js.
• “lessons/”: Organized Markdown content per section (01-…/A-… .md), with optional meta.json for section overrides.
• “data/” & “csv/” & “summary/”: Build-time scripts for generating CSV metadata and SEO summaries via ChatGPT.
• “public/”: Static assets (images, favicon).
• “styles/”: CSS variables & component styles.
• Config files: next.config.js, course.json, .github/workflows/next.yaml, package.json.
Key Insights from README
• Emphasizes: file-system routing, Markdown → React transformation, frontmatter usage, theming via CSS variables, CSV and SEO scripts, and automated GitHub Pages deployment via GitHub Actions.
Diagramming the Architecture
• Developer Workstation
• Next.js Build Pipeline
• Markdown Content Store (lessons/, course.json, meta.json)
• Data & Utility Scripts (csv/index.js, summary/)
• React Components & Context Providers
• Static Asset Store (public/images, styles/)
• Generated Output (/.next, CSV file)
• GitHub Actions CI/CD
• GitHub Pages Hosting
• End-User Browser
• Developer → (npm run build) → Next.js Build Pipeline
• Build Pipeline reads → Markdown Content Store & course.json
• Build Pipeline invokes → Data & Utility Scripts → produces CSV + enriched frontmatter
• Build Pipeline compiles → React Components + Context + styles → static HTML/CSS/JS
• Compiled output pushed → GitHub Repo → GitHub Actions → publishes → GitHub Pages Hosting
• End-User Browser → HTTP GET → Hosted Static Files → Hydrates React on client
c. Architectural Patterns & Principles:
• Static Site Generation (SSG) via Next.js
• File-system routing for dynamic lesson pages
• Separation of concerns: content vs. presentation vs. data-processing scripts
• Context API for global state (course metadata)
• Build-time extensibility (CSV / SEO augmenters)
d. Technologies & Frameworks to annotate:
• Next.js (SSG, dynamic routes)
• React (Components, Context API)
• .js (code syntax highlighting theme)
• Node.js scripts for CSV & ChatGPT SEO (OpenAI API)
• GitHub Actions (.github/workflows/next.yaml)
• GitHub Pages (static hosting)
• CSS variables & custom styles
Be Detailed but Not Overcomplicated
• Layer 1: Developer → Build Pipeline
• Layer 2: Source Content & Scripts → SSG Engine → Static Output
• Layer 3: CI/CD → Hosting
• Layer 4: End-User Interaction