A Cookbook is an invaluable resource, as it shows how to do various things in a clear fashion without all the theoretical context. 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.
The CL Cookbook aims to tackle all sort of topics, for the beginner as for the more advanced developer.
Thanks for contributing to the Cookbook.
You can start by having a look at the style guide.
When adding new content, please ensure it renders properly.
There are two ways to do this:
The first option is to install Jekyll globally and to run
jekyll serve in a folder where this repository was checked out.
http://127.0.0.1:4000/cl-cookbook/ (the last
/ is important).
Another option is to install the Jekyll version of this repository locally with Ruby gems. Since bundler 1.17.3 requires Ruby 2.5 that is rather old, it is recommended to install it using rbenv:
- Install rbenv using your package manager, or follow these instructions to install it manually.
- Install ruby-build. If you did a manual installation in the previous step, it is recommended to install ruby-build as a rbenv plugin.
rbenv install 2.5.0to install Ruby 2.5.0. Run
which gemto make sure it points to
- Run gem install bundler -v
2.1.4to install bundler.
cl-cookbookdirectory and run
bundle install --path vendor/bundleto install Jekyll locally.
bundle exec jekyll serveto generate the site and host it.
It can happen that you have older version of ruby installed in the system and bundler install will fail. To fix this, you need to update ruby. If system update is not an option, consider installing rbenv.
# Check rbenv homepage for install instructions on systems other than Mac OS X brew install rbenv ruby-build # Add rbenv to bash so that it loads every time you open a terminal echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile source ~/.bash_profile # Install Ruby rbenv install 2.5.0 rbenv global 2.5.0 ruby -v
After this you can proceed as usual:
gem install bundler
bundle install --path vendor/bundle
bundle exec jekyll serve
Also, refer to the CONTRIBUTING.md file.
Building the EPUB and the PDF
make epub. See
You need a decently recent version of Calibre. They provide an easy binary installation.
To exclude regions of text of the build (for example, embedded videos that makes no sense in a print format), use these flags:
<!-- epub-exclude-start --> <!-- epub-exclude-end -->
Our build script roughly does the following:
- concatenate all markdown content into one file
- change yaml frontmatters to a markdown title
- delete the mark regions from the file
- make internal links work on the EPUB.
It uses some metadata in
We can check the resulting EPUB with
This is a fork of the Common Lisp Cookbook, moved from SourceForge.
This project brings the Common Lisp Cookbook to this decade. Development of the original Common Lisp Cookbook 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. Most notably, Common Lisp users can now benefit from the Quicklisp library manager.
The main goal is making the Cookbook more modern and more accessible in addition to updating and expanding the content.
Development with GNU Guix
To enter a development environment in which all the required software dependencies are made available, run
guix shell in the project's root directory. The provided Guix manifest file will be automatically sourced after giving authorization for Guix to do so.
You can support the individuals that constantly improve the Cookbook. See the Github Sponsors icon. Thanks for them!