VSCode Setup

Starting a Project
Software Development Life Cycle (SDLC)

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!

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.

Open a terminal
Navigate to your project directory
Activate virtual environment (venv) source venv/bin/activate
Open VSCode code .
Open a VSCode Terminal
Type make This runs a build to a local server. Repeat this command as often as you make changes.
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 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 local server.
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.

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.

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.
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.

Test Changes on Local Server:

Open Terminal.
Be sure the “(venv)” prefix is in the prompt.
Type make in the prompt (run make).
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.

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.

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.

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.
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

Submit Feedback