A Guide to Setting up Jekyll for Complete Beginners

Published on 02 Nov 2022 | 10 minutes to read
#webmastery, #jekyll

Building this website has been both extremely empowering and humbling at the same time. I have a kanban board of ideas for what I want to tackle next (mostly behind the scenes stuff), but I’m often far beyond the limit of my current technical literacy. Without ever taking a single programming class, I often find myself unable to describe what it is that I want to create for my website in a way that triggers the right keywords of my web search for documentation, and it can get frustrating, but the payoff when things work just the way I want them to is so worth.

My latest persistence-filled project was figuring out how to get a blog onto this neocities site. Initially, I simply followed Sadness’ guide to the easiest way to make a ‘blog’ on Neocities, which leverages a Dreamwidth account. If you can copy+paste, you can complete the guide, and you’ll get a text editor on dreamwidth.org that looks more like what you’re probably used to for text editors with buttons to click for text styling (instead of having to learn/use markdown). Unfortunately, the UI looked dated in a way that didn’t make me want to blog and lacked dark mode. Most importantly, the RSS feed could only show posts within the last 14 days, which was the main kicker for me given that I didn’t expect to be blogging that much. I knew there had to be a better way for me.

Concurrently, I was also looking into a way to templatize my site in a way that didn’t rely on PHP since Neocities doesn’t supporting PHP. Essentially, I was looking to setup my site such that I would only have to see the content I wanted to edit with everything else inherited. I also wanted better code editor UX like instant previewing of my code changes (not possible with the neocities web-based code editor). I had been considering using a Static Site Generator, which would enable so much more than just a blog, but would require a non-trivial amount of effort on my part to understand because I’d need to send commands in Terminal, download Visual Studio Code for code editing, and more that I’d never done before.

Having given up on dreamwidth, I decided to give Jekyll (an SSG) + GitHub + VS Code a shot. As I went through the process of getting Jekyll up and running, I documented all the steps I took in the hopes that someone else with zero technical background like me can see what this entails end-to-end to determine if it’s something they want to try (plus, I’m trying to learn in public more, so this is me, creating the thing I wish I had found on the web):
 

  1. Install a code editor. I went with Visual Studio Code (VS Code)
  2. Create an account on Github.
  3. Install Jekyll
    1. Complete the Prerequisites
      1. Go to the Jekyll website: https://jekyllrb.com/docs/ to start with Step 1: installing all prerequisites, using the Windows guide, which says to use RubyInstaller.
      2. Open the RubyInstaller website that the page linked > click the version at the top of the list with the devkit
        1. For me, at time of writing, the version is Ruby+Devkit 3.1.2-1 (x64), which is what this webpage said to do under the section “WHICH VERSION TO DOWNLOAD?”.
      3. Click the .exe file to run the installer > Jekyll website said use all the default settings, so let’s speedrun this installation flow > click Finish.
      4. Type 3 > hit Enter key. The 3 is the option for “MSYS2 and MINGW development tool chain”, which is what the documentation that asks us to select.
      5. Now, after some loading, it says (among other things) that “Install MSYS2 and MINGW development toolchain succeeded”. Great. Now, we’re onto step 3 from the installation guide: Open a new command prompt window from the start menu, so that changes to the PATH environment variable becomes effective. I clicked to create a new tab on the terminal window I already had open and some text populated.
      6. Now the guide says, “Install Jekyll and Bundler using gem install jekyll bundler, so copy+paste that phrase into Terminal and hit Enter. A few seconds later, text will be streaming down Terminal.
      7. Once that text stream is finished, and it says a bunch of stuff, including “28 gems installed”, copy+paste jekyll -v on the next line.
      8. It returned “jekyll 4.3.1”, which means we’re done with Step 4
    2. Finish Quickstart
      1. Go back to https://jekyllrb.com/docs/ (we’ve already completed steps 1 & 2 listed)
      2. copy+paste  ./(choose whatever you want) into your terminal again to create a local location for the files of your site
      3. copy+paste cd (choose whatever you want) into terminal
      4. copy+paste bundle exec jekyll serve into terminal
  4. Create your website’s repository
    1. Go back to github.com > Create repository
    2. Specify a repository name. I went with lostletters, since that’s what my website name is, but you could use anything here.
    3. Description is optional. I went with “personal website”.
    4. Clicked Private since I don’t want anyone to see this hot mess yet.
    5. Checked the box for “Add a README file”
    6. For Add .gitignore, select the Jekyll template since we’re using Jekyll.
    7. Choose a license that makes sense for you. I went with BSD 2-Clause.
    8. Click Create repository
  5. Download GitHub Desktop
    1. With your repo open (https://github.com/username/reponame) > hit the green Code button > Open with GitHub Desktop
    2. This will take you to a new site to download GitHub Desktop, download it & run the .exe file
    3. Sign into GitHub > Authorize desktop
    4. Configure Git: Use my GitHub account name and email address > Finish
    5. Select your website repository from Your repositories > Clone (your repository name) > Hit Clone on the popup
    6. Open repository in your external editor: click Open in Visual Studio Code
    7. Do you trust the authors of the files in this folder? Check the box to Trustall the authors of all files int he parent folder ‘GitHub” > Click Yes, I trust the authors
  6. Download your site (assuming you’ve already created your site on Neocities): Go to your neocities.org Dashboard > Download entire site > unzip to the local folder from Step 3.2.2
  7. Make changes to your code
    1. Open your code editor (VS Code, for me) > File >Open Folder > select the folder that matches whatever you chose in step 3.2.2, so you can see all the files you just added.
    2. As you edit code, you’ll be able to see changes here once you save them in VS Code: http://localhost:4000/
      1. If you don’t see anything on localhost, then open terminal up again and complete Steps 3.2.3 and 3.2.4 again
    3. Save changes to files when you’re satisfied
  8. Update your GitHub Repo with recently saved files
    1. Open GitHub Desktop. You should see your changes reflected on the left side of the UI.
    2. Select the changes you want to push to your repo on GitHub, type a summary (required) > Commit to main > Push origin
      1. Note, you can have multiple commits before you push to your repo.
  9. Deploy files from GitHub to your Neocities site, using GitHub Actions. I completely followed this guide, so I’ll just point you there. Note: When you save that GitHub Action, it will be considered a push, which is what triggers the action (aka it will push your repo to Neocities), so definitely do this last.

That’s all for getting things setup! Now, whenever you want to make future changes to your site:

  1. Open up terminal (to send commands from steps 3.2.3 and 3.2.4 separately again to get localhost up and running)
  2. Open VS Code to make changes
  3. If you need to add graphics, save them to the local file folder on your computer that houses your site graphics (GitHub will see these new files and upload them to your repo as well in the next step)
  4. Open GitHub Desktop to commit as many changes as you want before you hit Push origin to force your GitHub repo and Neocities site to update.

Here are also some other folks who have explained similar processes as well, so you don’t have to go digging around the internet for those:

  1. cool-links.neocities.org/working_in_public.html
  2. grafo.zone/blog/presenceonneocities/ - a different way to update Neocities, using bash script & Bashcities


Next post: How to Write a Blog Comfortably with an SSG