How yousefalqafaz/github-slideshow works
Project type and purpose
• This is a *static-site presentation* repository built on Jekyll and Reveal.js, used by the GitHub Learning Lab bot to teach Git/GitHub concepts via an interactive slide deck.
File structure
• Top-level files:
• Gemfile/Gemfile.lock → Ruby dependencies (Jekyll).
• package-lock.json, node_modules → JavaScript dependencies (Reveal.js).
• _config.yml → Jekyll configuration.
• index.html, _layouts/, _includes/, _posts/ → Jekyll’s typical directory layout for templating and content.
• script/ → custom CLI scripts for setup, build (cibuild), serve, and stage.
• Notice the use of two build toolchains: Ruby/Jekyll for site generation, and Node/Reveal.js for slides.
README for additional insights
• The purpose is to serve as a GitHub Learning Lab course.
• It leverages the open-source Reveal.js project.
• Interaction with the “Learning Lab bot” occurs through GitHub Issues/PRs (external service).
Main components
a. Source Layer (Developer machine & Git repository)
• Markdown posts (_posts/*.md), HTML layouts/includes, configuration files.
• Gemfile, package-lock.json.
b. Build Layer (CI / Local build)
• Jekyll engine (Ruby) reads source + _config.yml → static HTML.
• Reveal.js (Node) assets integrated into the layout → slide deck HTML/CSS/JS.
• Custom scripts (script/cibuild, script/server, script/stage) orchestrate build, test, and staging.
c. Hosting Layer
• GitHub Pages (or another static host) serves the generated files.
d. Client Layer
• Web browser loads index.html → Reveal.js presents slides.
e. External Service
• GitHub Learning Lab bot interacts via GitHub API (issues/PR comments).
Relationships and data flows
1. Developer edits source → commits to Git → pushes to GitHub.
2. On push, CI (or script/cibuild) runs:
• bundle install → Jekyll build → produces _site/.
• npm install / npm run build → bundles Reveal.js assets.
3. script/stage or GitHub Pages takes _site/ → deploys to production.
4. End user’s browser requests slides → fetches static files from hosting → Reveal.js renders.
5. Learning Lab bot monitors repository via GitHub API → posts issues/PR comments → user interacts.
Architectural patterns and design principles
• Static Site Generator (SSG) pattern.
• Clear separation of concerns:
• Content (Markdown) vs. Presentation (layouts/includes).
• Build toolchains isolated in scripts.
• Infrastructure as code: build and deploy scripts version-controlled.
Essential elements
• Don’t omit the dual build toolchains (Ruby/Jekyll + Node/Reveal.js).
• Content directory structure feeding into Jekyll.
• Custom scripts orchestrating CI steps.
• Learning Lab bot as an external service to reflect the interactive teaching aspect.