How zamfiroiu/upb-cim works
Project Type and Purpose
• This repository is a static-site generator template for open educational resources (OER), built on Docusaurus.
• It provides lecture and practice content (Markdown, media, quizzes, code demos), a Docker-based build environment, and GitHub Actions workflows for linting, building, and publishing to GitHub Pages.
Main Components
a. Content Source
• “content/” folder: chapters subdivided into “lecture/” (slides, demos, media, quizzes) and “lab/” or “practice/” sections.
• “config.yaml”: Docusaurus site configuration (title, URL, base URL, social links).
• Common utility Makefiles and support code under “content/common/” for building demos and tests.
b. Build Environment
• Dockerfile: defines the builder image with Node.js, Docusaurus, reveal-md, MarkdownPP, Make.
• Local development: run Docker container mounting “/content” and “/output” to build and preview.
• Makefile recipes (in each chapter) that invoke MarkdownPP, reveal-md, and Docusaurus build steps.
c. CI/CD Pipeline (GitHub Actions)
• .github/workflows/super-linter.yml: static analysis of Markdown and code.
• .github/workflows/deployment.yml: on push to main or tagged commits, builds the site inside Docker, then deploys to the gh-pages branch.
• Workflow config files in .github/workflows/config/ and rules in .github/workflows/rules/ for lint customization.
d. Hosting and Delivery
• gh-pages branch: holds generated static files.
• GitHub Pages: serves the static site at https://<username>.github.io[/<repo>].
• End-users (students, instructors) access via web browser.
Relationships and Data Flows
1. Author edits Markdown, code demos, media in the “content/” tree locally.
2. Changes are committed & pushed to GitHub.
3. GitHub Actions triggers:
• Lint job validates Markdown and code.
• Build job: spins up Docker container → runs Makefiles → invokes MarkdownPP + reveal-md for slides, then Docusaurus build to produce static HTML/CSS/JS in _site/.
• Deploy job pushes _site/ output to gh-pages branch.
4. GitHub Pages serves the live site. Users view the static site in their browsers.
Architectural Patterns and Principles
• Static Site Generation (SSG): content-as-code, no runtime backend.
• Containerization: isolated, reproducible build environment via Docker.
• GitOps / CI-as-code: full build & deploy pipeline defined in version control.
• Modular content structure: chapters, lectures, labs all follow the same folder conventions.
Detailed Elements
• Source Control (GitHub repo)
• CI Jobs (Lint, Build, Deploy)
• Docker Builder (Dockerfile, mounted volumes)
• Build Tools (Make, MarkdownPP, reveal-md, Docusaurus)
• Output (_site/, gh-pages branch)
• Hosting (GitHub Pages)
• Clients (Web browsers)
Final Recommendations
1. Logical summary (Content → Build → Deploy → Serve)
2. Expanded view of the Build stage showing Docker + Make + Docusaurus.
• Avoid extraneous detail; focus on the CI/CD pipeline, static-site generation, and hosting path as the core architecture.