Files, Folders, and Project Structure

Why Project Structure Matters

When you visit a website, your browser needs to find and load several files: the HTML page, stylesheets, scripts, images, and fonts. Every one of those files lives at a specific path on the server. If the path is wrong, the file doesn’t load — and you get a broken page.

A consistent folder structure means:

• Your links always work — because files are where you expect them to be
• Other people can help — because the layout follows industry conventions
• Your project scales — adding new pages or features doesn’t create chaos
• Deployment is simpler — hosting platforms expect standard structures

The Standard Project Folder

Here is the folder structure used by most simple websites. You’ll see this pattern everywhere — in courses, documentation, and real production sites:

my-first-website/
├── index.html
├── about.html
├── contact.html
├── css/
│   └── style.css
├── js/
│   └── main.js
└── images/
    ├── logo.png
    ├── hero-banner.jpg
    └── icons/
        ├── email.svg
        └── phone.svg

Let’s break down each piece:

The root folder

The top-level folder (my-first-website/) is your project root. Everything lives inside it. When you open this folder in VS Code, it becomes your workspace.

index.html — The front door

Web servers look for a file called index.html by default. When someone visits yoursite.com, the server automatically serves index.html. That’s why your homepage should always be called index.html — not home.html, not main.html, not page1.html.

Additional HTML pages

Other pages like about.html and contact.html sit in the root alongside index.html. You link between them with simple relative paths:

<a href="about.html">About Us</a>
<a href="contact.html">Contact</a>

The css/ folder

All your stylesheets go here. Start with a single style.css file. As your project grows, you might add more:

css/
├── style.css          <!-- Main styles -->
├── reset.css          <!-- Browser reset (optional) -->
└── responsive.css     <!-- Media queries (optional) -->

You link to it from your HTML like this:

<link rel="stylesheet" href="css/style.css">

The js/ folder

JavaScript files live here. Start with main.js and add more as needed:

<script src="js/main.js"></script>

The images/ folder

All images, icons, and graphics go here. For larger projects, you can create subfolders like images/icons/ or images/blog/ to keep things tidy.

File and Folder Naming Rules

Bad file names are one of the most common causes of broken websites. Follow these rules and you’ll avoid hours of frustration:

The golden rules

1. Always use lowercase

   style.css — not Style.css or STYLE.CSS

   Web servers (especially Linux) treat uppercase and lowercase as different files. Style.css and style.css are two different files on a Linux server, even though they look the same on your Mac.

2. Use hyphens instead of spaces

   my-first-website — not my first website or My First Website

   Spaces in file names get converted to %20 in URLs, which looks messy and can cause bugs.

3. Stick to letters, numbers, and hyphens

   Avoid special characters like # @ ! & ( ). They have special meanings in URLs and can break your links.

4. Be descriptive but short

   hero-banner.jpg — not IMG_20240315_142356.jpg

   You should be able to tell what a file is without opening it.

5. Never remove file extensions

   Every file needs its extension: .html, .css, .js, .png, .jpg. The extension tells the browser (and you) what type of file it is.

Understanding File Paths

When you link to a stylesheet, image, or another page, you’re writing a file path — directions that tell the browser where to find that file. There are two types:

Relative paths (what you’ll use most)

Relative paths start from the current file’s location:

<!-- From index.html in the root -->
<link rel="stylesheet" href="css/style.css">
<img src="images/logo.png" alt="Logo">
<a href="about.html">About</a>

If you need to go up a directory level, use ../:

<!-- From a file inside a subfolder, e.g. pages/about.html -->
<link rel="stylesheet" href="../css/style.css">
<img src="../images/logo.png" alt="Logo">

Absolute paths (for external resources)

Absolute paths include the full URL. Use these for external resources like fonts or CDN libraries:

<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Raleway">

Common Mistakes That Break Websites

Here are the problems that trip up beginners most often — and how to avoid them:

Guided Practice: Set Up Your First Project

Independent Challenge: Portfolio Starter

Summary