How prd-nhat-nguyen/generative-ai-for-beginners works
Project type and purpose
• This is a documentation/course repository (“Generative AI For Beginners”) that uses Markdown lessons, code samples (Python, TypeScript, .NET), and Docsify to build a static website.
• It includes 21 lessons, each with “Learn” (theory) and “Build” (code samples) sections, plus multi-language support via an automated GitHub Actions translation pipeline.
File structure
• Top-level directories:
• 00-course-setup … 21-meta: per-lesson content with subfolders for Python, TypeScript, JavaScript, .NET, images.
• docs: contains Docsify config (index.html, _navbar.md, _sidebar.md), site assets.
• translations: holds identical lesson structure for each supported language.
• .github/workflows: CI/CD pipelines for translation, markdown validation, stale issues, welcoming.
• .devcontainer: Docker/Conda environment for local development.
• Support files: README.md (course overview), package.json/lock (Docsify dependencies), requirements.txt, environment.yml.
Key insights from the README
• Static site built with Docsify, hosted on GitHub Pages.
• CI/CD via GitHub Actions automates: translations, markdown linting, workflows on issues/PRs, build/deploy.
• Code samples connect to external services: Azure OpenAI Service, OpenAI API, GitHub Marketplace Models.
• Devcontainer to replicate environment locally.
a. Main components
• Content Repository (Markdown source, images, code samples)
• Translation Pipeline (GitHub Actions workflows that pull/push translations)
• Static Site Generator (Docsify + Node.js)
• CI/CD Orchestrator (GitHub Actions)
• Hosting (GitHub Pages)
• Devcontainer Environment (Docker + Conda for local preview)
• External AI Services (Azure OpenAI, OpenAI API, GitHub Models)
• Community/Support Links (Discord, Developer Forum)
b. Relationships & data flows
1. Developer pushes changes to GitHub
2. GitHub Actions “validate-markdown” → “lock” → “dependabot” → “translate” workflows run
3. Translations updated in translations/ directory
4. Docsify build (local or CI) reads docs/ + lesson markdown → generates static site assets
5. CI/CD deploys site to GitHub Pages (gh-pages branch)
6. End users access site via GitHub Pages URL
7. Code samples within lessons call external AI services at runtime
8. Devcontainer allows maintainers to run a local server for preview
c. Architectural patterns & design principles
• Content-as-Code (Markdown-driven content)
• Static Site Generation (Docsify)
• Monorepo Structure (all lessons & translations in one repo)
• CI/CD Pipeline (GitHub Actions for automation)
• Environment as Code (devcontainer.json + environment.yml)
• Separation of Concerns (content vs. build vs. hosting vs. translations)
d. Relevant technologies & frameworks
• Markdown, Docsify, Node.js
• GitHub Actions (YAML workflows)
• GitHub Pages (static hosting)
• Docker (devcontainer) + Conda (environment.yml)
• Python, TypeScript, .NET (code samples in lessons)
• Azure OpenAI Service, OpenAI API, GitHub Marketplace Model Catalog (runtime services)
Detail without overthinking
• Essential elements: content directories, build steps, translation pipeline, hosting, and runtime service interactions
• Keep translation languages represented as a single “Translations” component