Skip to content

Course Website Development Setup

Adam's course websites are generated by Jekyll, which creates static websites from Markdown files. When developing for these websites, you'll want to run them locally before pushing changes; you'll need a local installation of Ruby, ideally with a package manager.

Local Development

If you prefer to develop locally, we recommend installing Ruby via a version manager like rbenv. This simplifies the process of switching versions of Ruby, and ensures your Ruby installation won't conflict with any Ruby installation on your operating system (Ruby 2.6.10 is installed by default on macOS Sonoma, for example).

rbenv (macOS and other UNIX-likes)

Installation instructions for rbenv can be found on their GitHub README. You can install it using a package manager (e.g., Homebrew on MacOS), or directly by cloning the rbenv repository.

After installation, make sure to restart your terminal after running rbenv init if using a package manager or ~/.rbenv/bin/rbenv init if cloning directly.

Installing the ruby-build Plugin

To install Ruby using rbenv, the ruby-build plugin is required. If you installed rbenv using a package manager (Homebrew, AUR, or Fedora in particular), ruby-build and its dependencies will be installed automatically. On MacOS, you'll need to install XCode manually by running xcode-select --install. Then, you can proceed to install a version of Ruby.

If you installed rbenv by cloning, you'll need to install ruby-build manually; again, see the GitHub README. You'll also need to install the dependencies of ruby-build manually; those instructions are on their GitHub Wiki.

If you install rbenv manually, make sure to follow the relevant instructions to modify your shell to make ruby.

You should then repeat this process, swapping out rbenvfor wget.

Installing a Ruby Version

You can install multiple versions of Ruby simultaneously using rbenv. For Adam's website development, you should install Ruby 3.2.5 (rbenv install 3.2.5).

If this is the only Ruby project you are working on, it will suffice to set this as the global Ruby version (rbenv global 3.2.5). Otherwise, after cloning the website project to your machine, navigate to the directory and set 3.2.5 as the local Ruby version (rbenv local 3.2.5).

Verify everything is working as follows.

  • which ruby should output ~/.rbenv/shims/ruby.
  • rbenv version from the project directory should output 3.2.5.

Installing a Gemset Manager (Optional)

If you plan to do other Ruby development on your machine, you should keep the dependencies of each project separate using a gemset manager. Specifically, rbenv-gemset is the corresponding manager for rbenv.

Cloning the Git repository is the easiest way to install the plugin.

git clone https://github.com/jf/rbenv-gemset.git $HOME/.rbenv/plugins/rbenv-gemset

All the instructions for using rbenv-gemset are on their GitHub README.

You'll need a name for your gemset; for example, blank. Then, do the following from the project directory.

  • Verify your Ruby version is correct; rbenv version should output 3.2.5
  • If not, run rbenv local 3.2.5.
  • Verify there are no active gemsets; rbenv gemset active should output no active gemsets.
  • If not, run rm .rbenv-gemsets.
  • Run rbenv gemset init blank, or replace blank with whatever name you choose for the gemset.
  • Verify this worked with rbenv gemset active, which should output blank or blank global. (I'm not sure what the difference is between these two outputs.)

Running the Website

Most repositories come with a scripts repository.

You should run either ./install.sh or ./scripts/install.sh once (depending on where in the directory install.sh is stored for the respective website) to install the relevant gems, and then every time you need to run the website locally, run ./scripts/start.sh.

If the terminal is stuck on Generating... for a long time, try commenting out the line in _plugins/password.rb that starts with npx staticrypt... and rerunning ./scripts/start.sh. MAKE SURE TO REVERT THE CHANGE BEFORE YOU COMMIT ANYTHING.

Once the terminal says "Server running..." you can command-click on the Server address to open the website in your browser. From here, you can edit the address to access the specific page you need to.

Every time you git pull you will need to rerun ./scripts/start.sh. If the terminal encounters a "Conversion error: Jekyll::Converters::Markdown encountered an error while converting" after saving a file, try rerunning ./scripts/start.sh.

Bug Documentation

2024/08/08: @level_override is nil

jekyll 4.1.1 | Error:  undefined method `[]' for nil
C:/Ruby33-x64/lib/ruby/3.3.0/logger.rb:384:in `level': undefined method `[]' for nil (NoMethodError)

    @level_override[Fiber.current] || @level

The following error message was due to an outdated version of jekyll; updating to jekyll 4.3.3 fixed the issue.

2025/03/25: bundler is outdated

Configuration: macOS installation with Homebrew

Bundler 2.4.19 is running, but your lockfile was generated with 1.17.2. Installing Bundler 1.17.2 and restarting using that version.
Fetching gem metadata from https://rubygems.org/.
Fetching bundler 1.17.2
Installing bundler 1.17.2
/.rbenv/versions/3.2.5/lib/ruby/gems/3.2.0/gems/bundler-1.17.2/lib/bundler/shared_helpers.rb:272:in `search_up': undefined method `untaint' for "25sp":String (NoMethodError)

      current  = File.expand_path(SharedHelpers.pwd).untaint
                                                    ^^^^^^^^

The error message was due to an outdated version of bundler. Updating the bundler to the latest version fixed the issue:

bundle update --bundler

Once the bundler is updated, try re-running scripts/install.sh again.