The Common Lisp Cookbook survived a 2007 shutdown by moving to Jekyll and SBCL

A cookbook that is explicitly not a substitute for the HyperSpec

The Common Lisp Cookbook is a collection of Common Lisp recipes, described in the header as code-first. The README makes its own limits clear: a Cookbook is an invaluable resource, as it shows how to do various things in a clear fashion without all the theoretical context, and sometimes you just need to look things up. While cookbooks can never replace proper documentation such as the HyperSpec or books such as Practical Common Lisp, every language deserves a good cookbook, Common Lisp included.

That framing is the thing to hold on to when judging the project. It is a task-oriented reference, not a specification, and the author says so before describing the content. The audience is stated as both the beginner and the more advanced developer, and the stated aim is to tackle all sorts of topics.

The topic list in the repository root shows what that means in practice. There are chapters on arrays, CLOS, collections, data structures, databases, dates and times, debugging, dynamic libraries, editor support, an Emacs IDE chapter, equality, error handling, foreign function interface, files, functions, getting started, GUI, input and output, iteration, macros, numbers, the number tower, operating system interfaces, packages, pattern matching, performance and process management, among others.

Several of those chapter names are only meaningful to a Lisp reader. CLOS is about the Common Lisp Object System, the number tower is about the hierarchy of integer types, and packages is about the Common Lisp package system, which is the mechanism that gives Lisp its namespaces and which is the single biggest conceptual difference from most other languages in this guide's readership.

The project is a fork of the Common Lisp Cookbook moved from SourceForge, and the site is published at lispcookbook.github.io with EPUB and PDF editions in the releases.

Why a fork: the original stopped in 2007 and Quicklisp changed the ground

The Origins section tells the story more honestly than most project READMEs do.

This is a fork of the Common Lisp Cookbook, moved from SourceForge. The stated reason for the fork is that the project brings the Common Lisp Cookbook to this decade, and the reason the original could not be maintained is that development of the original in SourceForge halted in 2007. In the meantime, a lot has happened in the land of Common Lisp: tools and implementations have been improving, and some have fallen out of favor.

The change singled out is Quicklisp. The most notable development is that Common Lisp users can now benefit from the Quicklisp library manager. That is a specific and consequential shift. A large fraction of older Common Lisp code depends on libraries that had to be downloaded and configured by hand, and the presence of a library manager changed what idiomatic Common Lisp looks like in practice, not just in theory. A cookbook that predates Quicklisp would tell you to fetch a tarball and adjust your asdf systems, and that advice is now both harder and less relevant.

The main goal is stated as making the Cookbook more modern and more accessible in addition to updating and expanding the content. That is the maintenance thesis of the whole project, and it is also its risk. Modernising a two-decade-old recipe set is a distributed editorial problem, and unlike code, a recipe cannot be verified by a test suite.

The last push was on 2026-10-03, and the release history shows a 2026-09-12 release, a 2026-01 one and a 2025-01 one.

Three ways to run the site, and the Docker one is the easiest

The contributing section is mostly about getting the site to render, because a recipe that does not render is a recipe nobody can use.

The first option is to install Jekyll system-wide and run jekyll serve in a folder where the repository was checked out, then open http://127.0.0.1:4000/cl-cookbook/. The README notes that the last slash is important, which is the kind of detail that saves a contributor an hour.

The second option installs Jekyll locally with Ruby gems, and it is the one with the most ceremony. The stated reason is that bundler 1.17.3 requires Ruby 2.5, which is rather old, so it is recommended to install it using rbenv: install rbenv, install ruby-build as an rbenv plugin, run rbenv install 2.5.0, check that which gem points to ~/.rbenv/shims/gem, install bundler with gem install bundler -v 2.1.4, then bundle install --path vendor/bundle and bundle exec jekyll serve.

The third option avoids all of that. The README's reason is that it can be a bit troublesome to install older versions of Ruby onto newer Linux-based systems, so there is a Docker path:

sudo docker build -t cl-cookbook .
sudo docker run -p 4000:4000 -v $(pwd):/cl-cookbook cl-cookbook

The Dockerfile confirms the pinning, built FROM ruby:2.5, with bundler installed at version 2.1.2 and a bundle install whose failure is deliberately swallowed with the || true trick and the comment that this spawns warnings. The container command runs jekyll serve with --host=0.0.0.0 and --incremental, and the mounted volume means incremental builds are active, so you see your latest changes without restarting or rebuilding the container.

For a Guix user there is a fourth path: guix shell in the project root gives an environment with all the required software dependencies available.

The EPUB and PDF come out of SBCL, and the PDF path changed recently

The printable editions are built by a Common Lisp program, which is the appropriate choice and the one that produces the best result.

The Makefile targets are explicit. The epub target runs sbcl with make-cookbook.lisp loaded and the generate, to-epub and quit evaluations. The pdf target does the same with to-pdf and --disable-debugger. There is also epub+pdf, a sample-pdf target for the same script, and a check-release target that runs check-release.

The tools have moved. For the epub you need a decently recent version of Calibre. For the PDF, since 2025-10-01, you need Typst and Pandoc 3.8 or newer. That date is worth noticing, because it means the PDF pipeline was rebuilt on a different toolchain fairly recently, and the earlier approach is no longer what the project does.

The build script itself does something specific. It concatenates all markdown content into one file, changes yaml frontmatters to a markdown title, deletes the marked regions from the file, makes internal links work on the EPUB, and for the PDF transforms the big .md file to a typst file with Pandoc and then runs typst compile on it, which the README says produces a quality PDF. It uses some metadata in metadata.txt, and the resulting EPUB can be checked with epubcheck.

The exclusion mechanism is a detail worth knowing about if you contribute. To exclude regions of text from the output, for example embedded videos that make no sense in a print format, you wrap them in epub-exclude-start and epub-exclude-end comments.

macOS sed is the one build failure you will hit

The troubleshooting section documents a single failure mode, and it is a good one to know about before you hit it.

On macOS the build can fail with a UIOP/RUN-PROGRAM:SUBPROCESS-ERROR in a thread, where the subprocess command is sed -i "s/title:/# /g" full.md and it exited with error code 1. The explanation is that your sed program is non-GNU, and the fix is to install the GNU version with brew install gnu-sed, which puts gsed in your PATH. You then build with the environment variable pointing at it:

SED_CMD=gsed make epub

That is the reason the Makefile has SED_CMD ?= sed and exports it, and the reason the fix is an environment variable rather than a code change. The Makefile is designed to be told which sed to use, and the documentation is honest that the default is wrong on macOS.

There is a second troubleshooting path for the Ruby side. If you have an older version of ruby installed in the system and bundler install will fail, you need to update ruby, and if a system update is not an option, install rbenv. The shell snippet in the README adds rbenv to bash via a line appended to ~/.bash_profile, then sources it, then runs rbenv install 2.5.0 and rbenv global 2.5.0.

The common thread is that the toolchain is old and the documentation works around it rather than modernising it. That is a deliberate trade in a project whose goal is to update the content while keeping the original recipes recognisable.

Where the Common Lisp Cookbook is the wrong tool

The first wrong-tool case is stated in the README itself. If you need to know what a function does, what the specification says about an edge case, or whether an operator is standard, this is the wrong document, and the HyperSpec or a book such as Practical Common Lisp is what you want. The Cookbook's value is that it answers how do I do this, not what does this mean.

The second is verification. A recipe in a book is prose, and prose cannot be run. The Common Lisp case is unusually favourable here, because the project is written in a language with a compiler and a reader, so a recipe can in principle be executed, but the project does not describe a CI setup that runs every recipe against every supported implementation, and the chapter list shows how much surface there would be to cover. A recipe that worked on one implementation in 2007 may behave differently now, and the reader has to judge that.

The third is coverage. The chapter list is broad but a book is a fixed snapshot, and the ecosystem moves. Quicklisp is mentioned as the transformative change, and a cookbook that modernises its content has to keep modernising it, which is a permanent editorial obligation for a volunteer project.

The fourth is the toolchain. To contribute you need Ruby 2.5, bundler 2.1.4, Jekyll, and either GNU sed or the SED_CMD override, plus SBCL, Calibre, Typst and Pandoc 3.8 for the printable editions. That is a lot of machinery for a documentation project, and the Docker and Guix paths exist precisely because of it.

The licence is the one thing GitHub cannot classify, with the terms in the LICENSE file at the repository root, so anyone republishing content should read that file rather than assume a standard open source licence.

Editorial conclusion

The Common Lisp Cookbook fits a Common Lisp developer who needs a working example of a specific task today, and it does not fit a project that needs the language's specification, since the README is explicit that a cookbook can never replace proper documentation such as the HyperSpec. Before relying on it, read the chapter you intend to use rather than assuming the 2007-era advice still holds, because the fork's stated goal was modernisation, and note that the EPUB and PDF editions need SBCL, Calibre, Typst and Pandoc, so a contribution cannot be verified by reading the web version alone.

Frequently asked questions

Official sources

1. Issues
2. LispCookbook/cl-cookbook on GitHub
3. Project website
4. README
5. Releases