How iacopomasi/nlp works
Project type and purpose
• This is a static-site course website built with Jekyll (a Ruby-based static site generator) that hosts lecture materials (Jupyter notebooks, HTML slides, PDFs, figures) for an NLP course.
• The README describes the curriculum, links to NBViewer/Colab, and shows that lecture materials live under course/AAxxxx/... and notebooks/.
File-structure analysis
• Top-level:
• .github/workflows/notebook_release.yaml → CI/CD pipeline for building notebooks and site.
• _config.yml, _layouts/, assets/css/ → Jekyll configuration, HTML templates, CSS/SCSS assets.
• course/AA* → Lecture-by-lecture content directories with .ipynb, .html, .pdf, data, figs.
• notebooks/ → General notebooks for Part I.
• requirements.txt, postBuild, setup.cfg, environment.yml → Python/Jupyter environment specs (Binder, CI).
• Patterns:
• Static site generator (Jekyll)
• Notebook conversion (nbconvert)
• CI/CD via GitHub Actions
• Asset pipeline (SCSS → CSS)
README-driven insights
• Site is published to GitHub Pages
• Notebook links use NBViewer, Colab, and direct HTML exports
• No server-side code; fully static outputs
a. Main components
• Developer workstations (authors editing Markdown, HTML, SCSS, Jupyter notebooks)
• GitHub repository (source)
• GitHub Actions CI (.github/workflows/notebook_release.yaml)
• Build agents (Docker/Python environment with nbconvert + Jekyll)
• Jekyll engine (Ruby) + Notebook converter plugin
• Static assets (CSS, images, HTML slides, PDFs)
• GitHub Pages (web hosting/CDN)
• End users (students/instructors accessing site via browser, Colab, NBViewer)
b. Relationships & interactions
1. Developer → push to GitHub repo
2. GitHub Actions triggers on push → spins up container, installs Python env, runs nbconvert to export notebooks to HTML/PDF
3. Jekyll build step pulls in converted HTML, Markdown, layouts, SCSS → generates complete static site
4. CI commits build artifacts (if needed) or directly deploys to gh-pages branch
5. GitHub Pages serves final site to end users
6. External services: NBViewer/Colab badges link back to raw notebooks
c. Architectural patterns/design principles
• “GitOps” static-site workflow (source-of-truth in Git)
• CI/CD pipeline for reproducible content builds
• Clear separation: content source vs. build process vs. hosting
• Asset pipeline: SCSS → CSS, notebook conversion
d. Key technologies/frameworks
• Jekyll (Ruby)
• GitHub Actions (CI/CD)
• nbconvert (Python/Jupyter)
• SCSS/SASS (assets/css)
• GitHub Pages (hosting/CDN)
• Binder/requirements.yml (optional live environment)