Installing Jekyll on my M3 Macbook won't "stick"

I think I have painted myself into a corner trying to override the default Ruby install so that I can install Jekyll.

Here is a rough timeline:

1. I follow this tutorial to the letter and it works, my site is up
2. I install this theme, rebuild my site, and deploy successfully with Netlify
3. I start changing the site's configuration wrt layouts, menus, links, etc. Nothing related directly to Jekyll or Ruby configuration.
4. I try jekyll build and get jekyll not found
5. I try reinstalling Jekyll with gem install jekyll and get
   Successfully installed jekyll-4.3.3
1 gem installed
6. I try which jekyll to check installation and get jekyll not found
7. I ask Gemini for help and it tells me to try these commands in sequence for a clean install gem uninstall jekyll, sudo gem clean system, gem install jekyll --no-document
8. I quit and reopen my terminal and again try which jekyll and again get jekyll not found.
9. Because there are Jekyll items in gem list, Gemini advises that I probably have an environment variable issue and tells me to fix it by adding a line like export PATH="$PATH:/path/to/jekyll/bin" to my .zshrc file. I try to do this by finding the path with gem path but there are no Jekyll gem paths.
10. Gemini suggests I try installing Jekyll using rbenv so I do that and receive the following message
    Setting up your shell with `rbenv init zsh' ...
writing ~/.zprofile: now configured for rbenv.
    but there is no reference to rbenv in my .zprofile file

I am on a pretty new laptop so I am considering resetting to factory settings because this seems pretty intractable, but I am brand new to Ruby and Jekyll so I am posting here to see if there are any less drastic solutions. The pre-installed Ruby on mac seems to be just a huge pain!

Don't worry, you really shouldn't have to reset anything! You're correct that the built-in Ruby is a pain, as is the Homebrew Ruby. When I started out I got the most cryptic errors and they confused me for days!

As others have mentioned in the comments, a version manager like rbenv is a great idea! I personally really like mise right now. It's a polyglot version manager, so it handles basically any language, Ruby included. (asdf is another very popular polyglot version manager, but I recently switched to mise because I like its CLI better and it feels faster to me.) You can install mise with Homebrew: brew install mise.

The next element is zsh's init files, again as discussed in the comments. These can get kind of confusing, but here's a list of which files are read and executed when. I keep most of my configuration in .zshrc, but note that it's only executed for interactive zsh sessions.

These are the two pertinent lines in my .zshrc file:

eval "$(/opt/homebrew/bin/brew shellenv)"
eval "$(mise activate zsh)"

Since mise is installed with Homebrew, it's important that the Homebrew paths are added before calling mise activate zsh, because otherwise the mise executable won't be found.

Once you've added those lines to your .zshrc (or .zprofile or whichever relevant file from the list), make sure to refresh your shell session to pick up the changes: you can just close the Terminal window and open a new one, or you can run exec zsh (which replaces the current zsh process with a new one). You can make sure that mise is in your $PATH by running whence mise.

From there, using mise is super easy: cd to the directory of your project and run mise use ruby@latest (or, even better, mise use ruby@3.3.4 or whatever version you'd like, so your version is pinned). mise will install Ruby and will update $PATH to use the specified version. You can check this by running whence -a ruby; you should get something like this:

$ whence -a ruby
/Users/you/.local/share/mise/installs/ruby/latest/bin/ruby
/usr/bin/ruby

Now your mise-installed Ruby is in front of the system Ruby, and you're all set!

Hopefully this is at least a little helpful, and sorry this is so long!