DO NOT USE THIS GUIDE UNLESS YOU ARE CONTRIBUTING TO DOCUMENTATION!! THIS IS ONLY FOR SETTING UP THE JEKYLL DEVELOPMENT ENVIRONMENT

repo link: https://github.com/ut-ras/RobotathonESP32/tree/robotathon-guide-2025

windows setup

gl to linux/macos people. its mostly the same so u got it :)

Download VS Code

  1. Click big download button for Windows https://code.visualstudio.com/download
  2. Download the Dev Container extension

my_image.png :(

Download WSL

See official documentation here: https://learn.microsoft.com/en-us/windows/wsl/install

  1. Open Powershell
  2. Type wsl --set-default-version 2
  3. Type wsl --install
    • If you are prompted to put in credentials, put something you will remember

Unix systems do not show input while you are typing passwords by default! (type carefully :D )

Download Docker

Make sure to have Docker running for later!

Download Git

Set up SSH Authentication for GitHub

  • See existing Robotathon Guide doc here

Clone RobotathonESP32 Repository

  1. Go to the Robotathon repository
  2. Click the green <> Code button

my_image.png :(

  1. Copy the SSH Link (HTTPS bad and sucks 👎)
  2. Open Git Bash and navigate to where you want to keep the code by using ls and cd
  3. Run the following command in your Git terminal: git clone [LINK HERE] without the square brackets

Opening the Container

  1. Navigate to RobotathonESP32 by using ls and cd
  2. Type git checkout robotathon-guide-2025 to switch to the robotathon guide branch
  3. Open RobotathonESP32 in VS Code
  4. Click the >< icon in the bottom left corner of VS Code my_image.png :(
  5. Click Reopen in Container from the popup at the top of VS Code my_image.png :(

Setting Up and Using Jekyll (viewing local changes)

  1. Once everything has loaded, open a terminal within VS Code (View > Terminal, Ctrl + `, etc.)
  2. Type cd docs and press Enter
  3. Type bundle install and press Enter
  4. Type bundle exec jekyll serve --force_polling --livereload and press Enter
  5. Ctrl + Left Click on the server address link to open the site locally after it is done compiling

You do not need to rerun any terminal commands to view changes if you use the --force_polling and --livereload flags. If your computer is blowing up with constant autoreload, you can just use bundle exec jekyll serve, but you’ll have to rerun the command each time you want to render new local changes

my_image.png :(

Writing to Live Website

  1. Make change
  2. Navigate to RobotathonESP32 in Git Bash
  3. Commit and push changes (How?)
  4. Observe changes on live website in about a minute

How to migrate to developing next year’s Robotathon guide (only need to do for repository)

  1. Create copy of newest robotathon guide git checkout robotathon-guide-20xx git checkout -b robotathon-guide-202xx+1
  2. Navigate to /github/workflows/jekyll-gh-pages.yml in this repository and modify the name in the branches property to be robotathon-guide-202xx+1
  3. Make a modification to any of the content in /docs
  4. Push changes and wait for new website to deploy