Starting a Project

The following commands are universal for all machine types, terminals, and projects. The previous installation steps ensured that all machine types have compatible tools. Follow these steps in order:

Open a Linux-supported Terminal

You are using Ubuntu, Kali, MacOS in this step.

Clone repository

Use same repo that you modified in vscode.dev.

Change the commands below to use your own organization name (not “opencs” of “jm1021”). This is your personal template repository (not “open-coding-society/student.git”).

For example, if your GitHub organization is jm1021 and your repo is **student, use:

   cd                # move to your home directory
   mkdir -p jm1021   # use your organization name here
   cd jm1021         # use your organization name here
   git clone https://github.com/jm1021/student.git   # use your organization/repo here

Prepare project prior to opening VS Code

   cd student # Move to your personal project directory
   ./scripts/venv.sh # Activate the virtual environment (observe the prompt change)
   source venv/bin/activate # Prefix (venv) in path
   bundle install # Ensure Ruby gems for GitHub Pages is installed in (venv)
   code . # Open the project in VS Code

Authenticate with GitHub

  • At some point, you may be prompted to authenticate with GitHub. Follow the dialog and instructions.

For WSL Users Only

  • Ensure that VS Code is opened in WSL. Check the bottom-left corner of the VS Code window to confirm. This is critical for success! wsl

Software Development Life Cycle (SDLC)

The development cycle involves iterative steps of running the server, making changes, testing, committing, and syncing changes to GitHub. This process ensures that your website is updated and functioning correctly both locally and on GitHub Pages.

SDLC Workflow

+-------------------+       +-------------------+       +-------------------+       +-------------------+       +-------------------+
|                   |       |                   |       |                   |       |                   |       |                   |
|   Make Server     | ----> |   Change Code     | ----> |     Commit        | ----> |      Test         | ----> |     Sync          |
|                   |       |                   |       |                   |       |                   |       |                   |
+-------------------+       +-------------------+       +-------------------+       +-------------------+       +-------------------+
        |                           |                           |                           |                           |
        v                           v                           v                           v                           v
 Start Local Server           Edit Code Files           Stage Changes Locally        Verify Local Changes        Push Changes to Cloud

Open Project and Make

All students are building a GitHub Pages website. These steps get your website running on your desktop (local or cloud).

What is make?

Think of make as a smart task helper for developers.

  • It automates commands you would normally type one by one.
  • It starts a localhost server on you machine, enabling Testing prior to Sync.
  • It reads a special file called a Makefile, which lists tasks and how to run them.

Simply run:

make

And it will do everything listed in the Makefile.

  1. Open a terminal

  2. Navigate to your project directory

  3. Activate virtual environment (venv) source venv/bin/activate

  4. Open VSCode code .

  5. Open a VSCode Terminal

  6. Type make This runs a build to a local server. Repeat this command as often as you make changes.

  7. Hover then Cmd or Ctl Click on the localhost Server Address http://localhost: … provided in the terminal output from the make command.

### Congratulations!!! An output similar to below means tool and equipment success ###
(venv) johnmortensen@Mac pages % make
Stopping server...
Stopping logging process...
Starting server with current config/Gemfile...
Server PID: 40638
appending output to nohup.out
Server started in 17 seconds
    Server address: http://localhost:4500/
Terminal logging starting, watching server for regeneration...
Server started in 0 seconds
Configuration file: /Users/johnmortensen/opencs/pages/_config.yml
            Source: /Users/johnmortensen/opencs/pages
       Destination: /Users/johnmortensen/opencs/pages/_site
 Incremental build: enabled
      Generating... 
      Remote Theme: Using theme jekyll/minima
                    done in 16.396 seconds.
 Auto-regeneration: enabled for '/Users/johnmortensen/opencs/pages'
    Server address: http://localhost:4500/

Make workflow (local build: make, make dev, make clean, make stop, make convert)

These commands are used to build and manage a localhost version of the website. The purpose of this is to verify and test code changes prior to pushing changes to GitHub Pages.

  • make: Runs the full local server with all features and document overhead.

  • make dev: Runs a minimal, faster build intended for developers actively coding. Skips heavy document processing so the server starts and regenerates quickly. Use this when you are iterating on game logic, layouts, or interactive features and want rapid feedback.

  • make clean: Stops the local server and cleans the build files. Try this after rename as it could cause duplicates in build.

  • make stop: Stops the local server. This means you will be unable to access your blog on http://localhost until you run make again.

  • make convert: Converts Jupyter Notebook files. Run this if your .ipynb files are not updating on the server; it may assist in finding the error.

Make Debug Lab — Interactive Practice

Got errors? This interactive lab covers common make errors and browser DevTools debugging scenarios. Use the Learn tab for a quick reference, then test yourself in Practice by solving errors to reveal pixel art.

Click to open the Make Debug Lab

Make & DevTools Debug Lab

Learn to resolve common make errors and use browser DevTools to debug game issues

Make Errors Terminal

Make Not Found

make: command not found
'make' is not recognized as an internal or external command

Your system does not have make installed.

Install Xcode Command Line Tools
xcode-select --install
Verify installation
make --version
Install WSL
wsl --install
Install make in WSL
sudo apt update && sudo apt install make

No Makefile Found

make: *** No targets specified and no makefile found. Stop.

Make cannot find the Makefile. You are probably in the wrong directory.

Check current directory
pwd
List files to confirm Makefile exists
ls -la
dir
Navigate to project directory
cd /path/to/project

No Rule to Make Target

make: *** No rule to make target 'sever'. Stop.

The target you specified does not exist. Check for typos.

List available targets
grep "^[a-zA-Z]" Makefile
findstr /B /R "^[a-zA-Z]" Makefile
Fix the typo in your command — or use make dev for a faster build
make server
make dev

Missing Separator

Makefile:5: *** missing separator. Stop.

Commands in Makefiles must be indented with TAB characters, not spaces.

Open Makefile and go to the indicated line
Delete any spaces at the beginning of command lines
Press TAB key once before each command

Permission Denied

make: ./script.sh: Permission denied

The script does not have execute permissions.

Add execute permission
chmod +x script.sh
Run make again

Command Not Found in Makefile

make: *** [server] Error 127
/bin/sh: python3: command not found

The Makefile is trying to run a command that is not installed.

Check if command exists
which python3
where python3
Install the missing tool
brew install python3
winget install Python.Python.3

Game / Browser DevTools Errors DevTools

When building or debugging a game in your GitHub Pages project, use browser DevTools (F12 or Cmd+Option+I) to diagnose these common issues. Run make dev for a fast local server while iterating on game code.

Collision Bug — Elements View

Player passes through wall / hitbox looks wrong in the game

The collision box does not match the visible sprite. Inspect the element to see its real size and position.

Open DevTools → Elements tab (Cmd+Option+I → Elements)
Hover over the player or wall element in the DOM — the browser highlights its bounding box on screen
Check that width, height, and position CSS match your expected hitbox dimensions
Fix the discrepancy in your CSS or JavaScript collision logic
// Example: log element bounds in console const box = player.getBoundingClientRect(); console.log(box.width, box.height, box.x, box.y);

Style Bug — CSS View

Sprite is invisible, wrong color, or in the wrong position

A style rule is overriding your intended CSS. Use the Styles panel to find the conflict.

Open DevTools → Elements → Styles panel
Select the game element — look for strikethrough rules, which means a rule is being overridden
Identify the conflicting selector with higher specificity and either increase your specificity or remove the conflict
Toggle rules on/off live in the Styles panel to test fixes before changing code
/* Example: use a more specific selector to override */ #game-canvas .player-sprite { display: block; visibility: visible; }

CORS Error — Network View

Access to fetch at 'https://api.example.com/npc-data' from origin 'http://localhost:4500' has been blocked by CORS policy

Your game is fetching data (NPC configs, maps, scores) from a server that has not allowed your origin. Check the Network tab to diagnose.

Open DevTools → Network tab, then reload or trigger the fetch
Find the failing request (shown in red) and click it to see Response Headers
Look for Access-Control-Allow-Origin — if missing or wrong, the server must add it
As a local workaround during make dev, proxy the request through your Jekyll server or use a CORS-friendly test API
// Example: catch CORS errors explicitly fetch('https://api.example.com/npc-data') .catch(err => console.error('CORS or network error:', err));

Logic Bug — Player / NPC Interaction

NPC does not react to player / interaction triggers at wrong time

The interaction condition in your game logic has a bug. Use the Console and Sources tabs to step through the code.

Open DevTools → Console — look for errors or add console.log calls inside your interaction handler
Open DevTools → Sources → find your game JS file and set a breakpoint on the interaction function
Trigger the interaction in the game — execution pauses at the breakpoint so you can inspect variable values
Check distance/overlap calculations, event listener binding, and state flags (e.g., isNearNPC)
// Example: debug interaction check function checkInteraction(player, npc) { const dist = Math.hypot(player.x - npc.x, player.y - npc.y); console.log('distance to NPC:', dist, '| threshold:', npc.triggerRadius); if (dist < npc.triggerRadius) npc.interact(); }

Debug Art Challenge

Answer error clues correctly to reveal the hidden pixel art — now with DevTools challenges!

Progress
0/21
Correct
0
Errors
0

Click a number to solve its error

Current Clue

1 - Not Found
2 - No File
3 - Typo
4 - Tab
5 - Permission
6 - Tool
7 - Collision
8 - Style
9 - CORS
10 - Logic
Click a numbered pixel above to start!
Select any pixel with a number to see its error.
Build Successful!

You have mastered make and DevTools debugging

Accuracy
0%

VSCode Commit and Sync Workflow

All students will be writing and changing code. These steps allow you to change the website, first locally and then on public location.

+-------------------+       +-------------------+       +-------------------+       +-------------------+
|                   |       |                   |       |                   |       |                   |
|   VS Code Editor  | ----> |   Local Git Repo  | ----> |   Remote GitHub   | ----> |   GitHub Pages    |
|                   |       |                   |       |                   |       |                   |
+-------------------+       +-------------------+       +-------------------+       +-------------------+
        |                           |                           |                           |
        |                           |                           |                           |
        v                           v                           v                           v
    Save Files                Commit Changes               Sync Changes                Public Website
   Local Website

Detailed SDLC Steps

The SDLC adds the important steps of Make and Test to the workflow. This ensures that you never sync code that is broken locally. This helps the developer troubleshoot errors early and as you are working.

  1. Save Files in VS Code:

    • Edit your files.
    • Save the changes (Cmd + S on Mac or Ctrl + S on Windows/Linux).
    • Verify changes on the local web server.

  2. Commit Changes in VS Code:

    • Click on the “Source Control” icon in the left sidebar.
    • Stage your changes by clicking the plus sign next to the files.
    • Enter a commit message.
    • Click the “Commit” button.

  3. Test Changes on Local Server:

    • Open Terminal.
    • Be sure the “(venv)” prefix is in the prompt.
    • Type make in the prompt (run make).
    • If you are actively developing a game or interactive feature, use make dev instead — it skips heavy document processing for a faster build cycle.
    • If successful, you will see log output in the prompt:
        Server address: http://localhost:4500/
    • If delayed open 2nd terminal using + and execute command cat \tmp\jekyl4500.log. This keeps ongoing history of logs if things are right a below, if things are wrong you will see errors.
    (venv) johnmortensen@Mac pages % cat /tmp/jekyll4500.log 
Configuration file: /Users/johnmortensen/opencs/pages/_config.yml
            Source: /Users/johnmortensen/opencs/pages
      Destination: /Users/johnmortensen/opencs/pages/_site
Incremental build: enabled
      Generating... 
      Remote Theme: Using theme jekyll/minima
                  done in 16.396 seconds.
Auto-regeneration: enabled for '/Users/johnmortensen/opencs/pages'
   Server address: http://localhost:4500/
Server running... press ctrl-c to stop.
      Regenerating: 1 file(s) changed at 2025-11-20 06:20:27
                  _posts/Foundation/B-tools_and_equipment/2025-04-15-tools_setup-vscode.md
      Remote Theme: Using theme jekyll/minima
                  ...done in 16.992685 seconds.
                     
      Regenerating: 1 file(s) changed at 2025-11-20 06:22:30
                  _posts/Foundation/B-tools_and_equipment/2025-04-15-tools_setup-vscode.md
      Remote Theme: Using theme jekyll/minima
                  ...done in 16.763741 seconds.
    • Open the localhost Server address in deskop or cloud computer browser http://localhost:4500/
    • Test your changes before you commit.
  4. Errors in terminal
    • Most likely cause is (venv) in prompt (venv) johnmortensen@Mac pages %. This will fail 100% of the time
    • If there are errors in coding the will show in terminal (with a delay/timeout) and be in log: cat /tmp/jekyll4500.log
    • Most likely error, is what you just changed!!! Easiest fix is to undo, see if it fixes things. Then try again.
  5. Regeneration messages
    • Most changes will show regeneration message in terminal after you save file.
    • If you see a message in terminal like the one below, you can test your localhost change by refreshing page you are working on.
    Regenerating: 1 file(s) changed at 2025-11-20 06:40:18
                  _posts/Foundation/B-tools_and_equipment/2025-04-15-tools_setup-vscode.md
      Remote Theme: Using theme jekyll/minima
                  ...done in 16.537365 seconds.

  6. Sync Changes to GitHub:

    • Never sync changes before you test, as this activates Actions on GitHub.
    • Click the “Sync Changes” button in the Source Control view.
    • This pushes your local commits to the remote GitHub repository.

  7. Update GitHub Pages:

    • GitHub Pages Action automatically rebuilds your site with the latest changes.
    • Visit your public website at https://.github.io/student to see the updates.
flowchart TD
    A[Run Server] --> B[Make Changes]
    B --> C[Commit]
    C --> D[Test]
    D --> E{Tests Pass?}
    E -- Yes --> F[Sync]
    E -- No  --> B

   style E fill:#FF0000