Jon Lee

website guide

Setup to preview website changes

The most basic computer setup requires that any changes you make can only be seen once they are published publicly. It would be nice to make sure that those changes look good before making them public. To do this, however, we will need to introduce a third app called Terminal (already installed on Macs) into the workflow, and install Ruby and Jekyll onto your system.

Install Ruby

Ruby is a programming language. It is used to create your website.

  1. Open, either via Finder (Applications > Utilities > Terminal) or through Spotlight (click on the magnifying glass in the top menu bar, or use the shortcut Command-Space).

  2. In Terminal, install brew by entering the following command:
     /bin/bash -c "$(curl -fsSL"

    You may be asked to press Enter to confirm installation. Press Enter.

    Installation may include downloading large software packages like Command Line Tools for Xcode. This may take a short while to complete.

  3. Add Homebrew to PATH in ~/.zprofile. Depending on the OS the paths may change. Be sure to look at the command line output to determine which path to use.

    On newer macOS, you’ll see /opt/homebrew/bin, while on older macOS it will be /usr/local/bin/.

    Newer macOS:

     touch ~/.zprofile
     echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
     eval "$(/opt/homebrew/bin/brew shellenv)"
     brew doctor

    Older macOS:

     touch ~/.zprofile
     echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
     eval "$(/usr/local/bin/brew shellenv)"
     brew doctor

    In Terminal you should see Your system is ready to brew.

  4. Install ruby-install and chruby:
     brew install ruby-install chruby
  5. When the install finishes, you will see instructions for updating the file ~/.zshrc. The command will differ depending on the processor of your computer, but the message appears something like:
     Add the following to the ~/.bash_profile or ~/.zshrc file:
       source /opt/homebrew/opt/chruby/share/chruby/
     To enable auto-switching of Rubies specified by .ruby-version files,
     add the following to ~/.bash_profile or ~/.zshrc:
       source /opt/homebrew/opt/chruby/share/chruby/

    Keep track of this as we’ll need it a little later.1 Don’t close the window yet since we need to copy-paste these commands.

  6. Open a new Terminal window through Terminal > Shell > New Window (Command-N).

  7. Install Ruby:
     ruby-install ruby 3.1.3

    This will take a few minutes.

  8. Open ~/.zshrc for editing by typing:
     touch ~/.zshrc
     open -e ~/.zshrc

    This will likely open the file in TextEdit.

    1. In that app, add the commands listed before to the end of the file. Make sure the directories below match what you saw in Terminal earlier.
       source /opt/homebrew/opt/chruby/share/chruby/
       source /opt/homebrew/opt/chruby/share/chruby/
       chruby ruby-3.1.3
    2. Save the file.
    3. Close the file window.
    4. Quit TextEdit.
  9. Open a new Terminal window.

  10. Verify that Ruby is installed by running the command below:
     ruby -v
  11. You should see something like ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [arm64-darwin22]. The version of Ruby installed should be 3.1.3.

Install Jekyll

Jekyll is a static site generator. It processes the files in your repository and outputs basic HTML, JS, and CSS files. GitHub uses Jekyll to generate your site. Jekyll is written in Ruby.

It’s a “static” site generator because it doesn’t support running business logic on web servers, which are necessary for e-commerce or SaaS like Shopify or Google Docs. It’s made for simple websites. We add more sophisticated functionality to your website by integrating the services of other products (like Formspree for contact form submission).

  1. Install jekyll:
     gem install jekyll
  2. GitHub Pages is GitHub’s website service which uses Jekyll. It uses a specific, and older, version of Jekyll. That version has certain software dependencies we should install. To do this, you need to have your website downloaded locally onto your computer.

    1. Change Terminal’s working directory to the directory containing your website, which is your local repository:
       cd <directory-to-repository>

      Enter the path to your repository where <directory-to-repository> is above. One way to do it is to drag the folder icon to your repository in Finder, into Terminal.

    2. Install the Jekyll dependencies:
       bundle install
  1. Depending on the processor type of your Mac, the directory may be /usr/local/opt or /opt/homebrew/opt

  • Updates:
  • 20 Sep 2023 — Added commands for older macOS, and add touch in case ~/.zshrc doesn’t exist.

Hi! Have a comment, question, complaint, observation, or criticism about this post? Leave your comment below!