# The Missing Semester of Your CS Education: what the repository actually contains > The site behind MIT's Missing Semester course is a Jekyll build with a Docker path for contributors who do not want Ruby on their machine. The content is CC BY-NC-SA 4.0, and the repository is a website, not a course you run. **missing-semester/missing-semester** — The Missing Semester of Your CS Education 📚 - Repository: https://github.com/missing-semester/missing-semester - Website: https://missing.csail.mit.edu/ - Stars: 6,089 · Forks: 1,434 - Language: CSS - License: NOASSERTION - Published: 2026-09-22 · Updated: 2026-09-22 · Language: en - Canonical page: https://hysenlabs.com/projects/missing-semester-missing-semester ## What the missing-semester repository is, and what it is not The repository is the source of the website at missing.csail.mit.edu, not a piece of software you install to learn shell commands. The README opens by calling it the website for The Missing Semester of Your CS Education and then invites issues and pull requests. Everything in the tree supports that one job: _layouts/ and _includes/ hold the page templates, static/ holds assets, index.md and lectures.html are pages, and the _2019/, _2020/ and _2026/ directories hold per-year course material. The primary language is CSS, which tells you where the weight sits: presentation, not a runtime library. If you arrived expecting a CLI, a package on npm, or a tool that grades your exercises, the repository will not give you one. It gives you the course site and the lecture notes behind it, and the lectures themselves are the teaching material. ## How the Jekyll site is put together The build is a standard Jekyll pipeline. _config.yml drives the site configuration, markdown pages are rendered through the layouts in _layouts/, and shared fragments come from _includes/. The year directories (_2019/, _2020/, _2026/) are the mechanism for keeping multiple editions of the course side by side rather than overwriting one another; past.md and lectures.html are the entry points that surface them. Two GitHub Actions workflows guard the result: build.yml compiles the site, and links.yml checks the links. That second workflow matters more than it looks. A course site accumulates external references to tools, papers and documentation over years, and link rot is the failure mode you would otherwise only notice from a reader's email. The Dockerfile pins the runtime to ruby:3.4-alpine3.21 and installs ruby-dev and alpine-sdk before running bundle install, so the container reproduces the same gem set recorded in Gemfile.lock. Nothing here is exotic, and that is the point: the site is meant to be built by contributors, not maintained by a platform team. ## Building the site locally with bundle exec jekyll serve The README gives one command for local development. Run it from the repository root with Ruby and Bundler already present; Jekyll serves the site and watches for file changes, so editing a markdown page or a layout triggers a rebuild without restarting the process. ```bash bundle exec jekyll serve -w ``` The README does not state the port in this section, but docker-compose.yml maps 4000:4000 and the Docker instructions point at http://localhost:4000, so that is the address to try. If the command fails before serving anything, the usual cause is a missing gem installation rather than a problem in the repository; the README assumes you have run bundle install against Gemfile.lock first. The -w flag is what makes this usable for editing: without it you would restart the server after every change. ## The Docker path, for contributors who do not want Ruby installed The README offers a container route explicitly to avoid installing Ruby and its dependencies on the host. One command builds the image from the local Dockerfile and starts the service. ```bash docker compose up --build ``` The compose file mounts the repository into /app as a volume, so edits on the host appear inside the container, and Jekyll rebuilds as you change files. The container command is bundle exec jekyll serve -w --host 0.0.0.0, which is why the port mapping to the host works at all; binding to 0.0.0.0 inside the container is what lets http://localhost:4000 reach it. Two details are worth knowing before you rely on this. The service is declared with restart: on-failure, so a container that exits because of a bad Gemfile or a syntax error in _config.yml will restart rather than stay down, and you may need to read the logs rather than assume the process died quietly. And the image tag is missing-semester:latest, built locally, so there is no published image to pull; the first run is a full build. ## Where this repository is the wrong tool The most common mismatch is categorical. People search for the Missing Semester expecting a course they can install, and the repository is the website that hosts it. Cloning it gives you Jekyll templates and lecture markdown, not a shell environment, not an exercise runner, and not the videos. The videos are referenced by the course but the repository holds the site, and the README describes the content licence rather than bundling media. A second limitation is the licence. Everything in the course, including the website source code, lecture notes, exercises and lecture videos, is under CC BY-NC-SA 4.0. That is a non-commercial, share-alike licence, which is a real constraint if you want to fold the notes into paid training material or a commercial product. The README points to the license page for contributions and translations, and license.md is the file to read before you plan anything derivative. Third, there is no release history in the repository, so there is nothing to pin against: you track the master branch, and the build is whatever the current commit produces. For a course site that is acceptable; for anything you depend on programmatically it would not be. ## How it compares with a static-site generator like Hugo If your goal is to publish a course site, the honest alternative is a different generator, and Hugo is the usual one. The difference is not quality, it is the toolchain you have to keep alive. Jekyll is Ruby: this repository carries a Gemfile, a Gemfile.lock, and a Dockerfile that installs ruby-dev and alpine-sdk to make native gem extensions compile. Hugo ships as a single binary with no runtime to install and no lockfile to reconcile. What you give up by leaving Jekyll is the plugin and layout ecosystem this site already uses, and the Liquid templates in _layouts/ and _includes/ that contributors have already written. For a project whose contributors are students and instructors rather than full-time web developers, the container path exists precisely because the Ruby setup is the friction point. If you are starting a new course site from scratch and do not need Jekyll's plugin set, a single-binary generator removes a dependency you would otherwise maintain for years. If you are contributing to this site, the choice is already made for you. ## Licence terms and the cost of keeping the site current The licence is CC BY-NC-SA 4.0 across the course content: website source, lecture notes, exercises and videos. Attribution, non-commercial use and share-alike are the conditions, and the repository's license.md is the place the project itself points to for contributions and translations. The practical implication for a translator or an instructor reusing the notes is that derivative work inherits the same terms and cannot be sold. This is not legal advice, and the licence text governs. On maintenance, the last push to the repository was on 2026-09-21, and the repository is not archived, so the site is being touched. The upgrade cost is low but not zero: the Dockerfile pins ruby:3.4-alpine3.21, and Gemfile.lock pins the gem set, so the build is reproducible until someone bumps either. The link-checking workflow is the recurring cost that never goes away, because external documentation moves and the course cites a lot of it. For a contributor, the realistic work is content edits and link fixes, not dependency surgery. ## Conclusion Adopt this repository if you want to build, translate or fix the course website, or if you want to read the lecture notes and exercises as they are written. Do not adopt it if you are looking for a course you install and run: the repository is a Jekyll site, and the shell, Git and tooling lessons live in the lecture content, not in the code. Before contributing, verify the Ruby and Bundler versions against Gemfile.lock, confirm that port 4000 is free, and read license.md, because the CC BY-NC-SA 4.0 terms cover the lecture notes and videos as well as the site source. ## FAQ ### What is the Missing Semester of Your CS Education? It is a course site for The Missing Semester of Your CS Education, hosted at missing.csail.mit.edu, with lecture notes and exercises covering material a computer science curriculum often leaves out. This repository is the website source for that course, built with Jekyll. ### Is the Missing Semester repository the course itself? No. The README describes it as the website for the course, and the tree holds Jekyll layouts, includes, static assets and per-year content directories. The teaching material lives in the lecture notes and videos, not in code you install and run. ### How do I build the Missing Semester site locally? The README gives bundle exec jekyll serve -w for a local Ruby setup, or docker compose up --build to build and run it in a container. The Docker instructions point to http://localhost:4000, matching the 4000:4000 port mapping in docker-compose.yml. ### What licence covers the Missing Semester course content? The README states that all content in the course, including the website source code, lecture notes, exercises and lecture videos, is licensed under CC BY-NC-SA 4.0, and points to the license page for contributions and translations. ### Is there a published Docker image for the Missing Semester site? The compose file references missing-semester:latest with a local build context and a Dockerfile, so the image is built on your machine rather than pulled. The first docker compose up --build is a full image build. ## Sources - [Issues](https://github.com/missing-semester/missing-semester/issues) - [missing-semester/missing-semester on GitHub](https://github.com/missing-semester/missing-semester) - [Project website](https://missing.csail.mit.edu/) - [README](https://github.com/missing-semester/missing-semester/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/missing-semester-missing-semester