Project structure, code editors, local testing and Git

A single page is easy to manage. A website with several pages, a stylesheet, a script and some images quickly becomes a pile of files, and one wrong edit can break something that worked yesterday. Professionals deal with this using two habits: a tidy folder structure and version control. This lesson teaches both, using small, safe steps in a practice folder.

A tidy project folder

A website project is just a Folder of files. What matters is that you can find things and that the links between files keep working. A common simple layout puts the home page at the top, called index.html because web servers show that file first when someone visits a folder, and gives other kinds of file their own subfolders.

Follow a few naming rules from the start: use lower-case letters, no spaces (use a hyphen, as in my-photo.jpg), and no accents or odd symbols. Web addresses and Linux treat Photo.JPG and photo.jpg as different files, so a link that works on a Windows laptop can break after publishing. A path such as css/style.css is a relative path: it starts from the page that contains it.

<link rel="stylesheet" href="css/style.css">
<img src="images/photo.jpg" alt="Amina holding a basket of tomatoes">
<a href="about.html">About me</a>
<script src="js/script.js" defer></script>

Choosing a code editor

You can write code in Text Editor or Notepad, and for a first page that is fine. A code editor adds things that save time and prevent mistakes: colours for different parts of the code, matching brackets, automatic indentation, a file list for the whole project and search across all files. Visual Studio Code is a free and very widely used editor for Ubuntu and Windows. Others exist, such as Sublime Text and, on Linux, GNOME Text Editor for lighter use. Choose one and learn it well rather than trying many.

Testing on your own computer

You do not need the internet to test a website. Open index.html in a browser (double-click it or drag it onto the browser window) and the browser reads it straight from your disk. The address bar will start with file://. The working routine is: edit, save, switch to the browser, refresh with F5, look. If a change does not appear, a hard refresh with Ctrl+Shift+R asks the browser to ignore its stored copy of the page.

Version control with Git

Have you ever saved essay-final, essay-final2 and essay-really-final? Git solves that problem properly. It is a free tool that records the history of a project folder. A folder tracked by Git is called a Repository, or repo. Each time you reach a good point you make a commit: a saved snapshot plus a short message saying what changed. You can look back at any commit and return to it if something breaks.

A branch is a separate line of work. The main line is usually called main. To try a risky idea you create a branch, work there, and either merge it back into main if it works or throw it away if it does not. GitHub is a website that stores copies of repositories online, which gives you an off-site backup and a way to share and publish. Git is the tool on your computer; GitHub is one place to keep a copy. They are not the same thing.

Your first repository

git --version
sudo apt install git

git config --global user.name "Amina Wanjiru"
git config --global user.email "amina@example.com"

mkdir -p ~/practice/my-site
cd ~/practice/my-site
git init
git branch -M main

git --version

git config --global user.name "Amina Wanjiru"
git config --global user.email "amina@example.com"

New-Item -ItemType Directory -Force $HOME\practice\my-site
Set-Location $HOME\practice\my-site
git init
git branch -M main

Create an index.html file inside my-site with your editor (any content, for example a heading), save it, then ask Git what it sees. git status is the command you will use most: it shows which files are new, changed and ready to be saved. Then git add index.html puts the file in the next snapshot, and git commit -m "..." saves it with your message.

git status
git add index.html
git commit -m "Add home page"
git log --oneline

To make and try a branch, git switch -c new-colours creates and moves to a branch of that name, and git switch main returns. To put the project on GitHub, create an empty repository on the website, then follow the two or three lines it shows, which look like git remote add origin <address> and git push -u origin main. GitHub no longer accepts your account password for pushes from the command line; it asks for a token or a browser sign-in, and the page will explain the current method. We do that as part of the next lesson.