0.1 Pre-Flight Check

Before we start, verify that you have the necessary tools installed on your computer.

Open your Terminal and run these commands:

git --version
node -v
npm -v

1. Workspace Setup

First, let's create a clean place on your computer to keep your code. We will create a folder called repos in your home directory.

Copy and paste these commands one by one:

# This takes you to your Home folder
cd ~

# This creates a new folder named 'repos' (safe if it already exists)
mkdir -p repos

# This goes inside that new folder
cd repos

open .

2. GitHub Registration and Repository

We need a place on the internet to store your code so others can see it.

Goal: Create your personal website repository (this is what GitHub Pages publishes).

1. Go to GitHub.com and sign up (or log in).
2. Click the + icon (top right) → New repository.
3. Important: Name the repository exactly like this:

(Double check that you spelled your username correctly!)

• Owner: nickname
• Repository name: nickname.github.io
• Public: Select "Public".
• Add README: Leave this unchecked (empty).

Click Create repository.

3. Configure Git and SSH Keys (one-time)

If this is your first time using Git on this computer, you need to introduce yourself.

git config --global user.name "Your Name"
git config --global user.email "surname@isl.cy"

3.1: Generate the key

ssh-keygen -t ed25519 -C "surname@isl.cy"

3.2: Activate the key

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

3.3: Upload key to GitHub

Now copy the key to your clipboard:

pbcopy < ~/.ssh/id_ed25519.pub

1. Go to GitHub website -> Click your profile photo (top right) -> Settings.
2. On the left menu, click SSH and GPG keys -> New SSH Key.
3. Title: "Macbook" (or any name).
4. Key: Paste (Command+V). It should start with ssh-ed25519.
5. Click Add SSH key.

ssh -T git@github.com

4. Clone and Prepare Folders

• 📂 myproject: This is your Workbench. You write code here.
• 📂 nickname.github.io: This is your Public Display. Files here go to the internet.

# Ensure we are in the repos folder
cd ~/repos

# 1. Download your GitHub Pages repository (it is currently empty)
git clone git@github.com:nickname/nickname.github.io.git

# 2. Create a folder for your source code
mkdir myproject

ls -F ~/repos

rm -rf ~/repos/myproject
rm -rf ~/repos/nickname.github.io/

6. Install WebStorm and open your project

1. Open WebStorm. Click Open.
2. Navigate to repos -> myproject and click Open.

7. Install and Build

Inside WebStorm, click Terminal at the bottom left.

pwd

npm install

7.1. Update configuration for GitHub (CRITICAL)

Your website will live at: https://nickname.github.io/myproject/
However, the default code assumes it lives at the root /. We must fix this mapping.

1. Open vite.config.ts in WebStorm.
2. Find the config object that starts with return {.
3. Add (or update) the base line exactly like this:

export default defineConfig(({ mode }) => {
  // ... some code ...
  return {
    base: "/myproject/",    // <--- ADD THIS LINE (Watch the slashes!)
    server: {
      // ...

7.2. Build and Test

# Create the optimized website files
npm run build

To check if it works locally, run npm run dev. Press Ctrl+C to stop when done.

8. Copy Result and Push to GitHub

We will use the terminal to move the built site (dist) to the GitHub folder.

# 0. Go to the GitHub repo folder
cd ~/repos/nickname.github.io

# 1. Create a folder for this specific project inside your website
mkdir -p myproject

# 2. COPY the finished site. Warning: Type this carefully!
# (The spaces and dots matter)
cp -a ~/repos/myproject/dist/. ./myproject/

ls ./myproject/index.html

If the check passed, upload to GitHub:

# 3. Check status (You should see red or green text)
git status

# 4. Upload
git add .
git commit -m "Deploy myproject"
git push