How lawrennd/old_talks works
Project type and purpose
• This is a static‐site “talks” generator for Neil Lawrence’s lecture and seminar materials.
• Source content is organized as Markdown + macros; build tools transform it into HTML (talk pages, slides, notebooks).
File structure
• Top‐level files:
• README.md – explains build dependencies (gpp, makemd)
• Makefiles, shell scripts, custom Python under /maketalk
• Content directories: each _subject/ folder (e.g. _ai, _data-science, _ml, etc.) with:
• Markdown talk files
• _config.yml – subject‐specific configuration
• includes/ – reusable fragments
• Build orchestration: multiple make-*.mk, maketalk/ preprocessor modules
Key insights from README
• Uses gpp (generic preprocessor) + Python package makemd to interpret macros in Markdown.
• Build flow: Markdown → gpp macros → makemd → HTML, slides, notebooks
Main components
a. Source content layer
b. Preprocessing & build engine
• gpp preprocessor
• makemd Python package
• Custom scripts in maketalk/
• Makefiles and shell wrappers (make-*.mk, recompile_lectures.sh, etc.)
c. Output artifacts
• Generated HTML pages (talks, index.html)
• Slide decks under slides/ (HTML, PDF, PPTX)
• Jupyter notebooks (.ipynb)
d. Deployment/Hosting
• Static web server (e.g., GitHub Pages, Nginx)
Relationships & interactions
• Developer edits source Markdown → triggers make talk (or top‐level make-*)
• Makefile calls gpp to expand macros → passes to makemd → invokes maketalk modules to produce intermediate Markdown/HTML
• Final static tree is served by web server
Architectural patterns & principles
• Content‐centric pipeline (Content → Transform → Serve)
• Separation of concerns:
• Content vs. build logic vs. runtime assets
• Layered build pipeline with small, reusable macros and includes
Technologies & frameworks
• gpp (generic preprocessor)
• Python + makemd
• GNU Make / shell scripts
• Reveal.js for slides
• Jupyter notebooks
Detailed elements
• Build orchestrator (Makefiles + maketalk/)
• Preprocessor & macro engine (gpp → makemd → custom Python modules)
• Output folders (output/html/, slides/, notebooks/)
• Hosting layer (static web server or CDN)