Organize your first website

A useful starting point, not a universal rule

A website is often a group of files that work together. HTML describes the page, CSS controls how it looks, JavaScript adds behavior, and image files provide pictures. Keeping related files together makes it easier to find things and understand how the page is built.

There is no single correct folder structure for every website. A tiny project can keep index.html, styles.css, and script.js beside each other. A larger project may group files by feature, page, or framework. Follow your team's conventions when they exist. This guide uses one small example so we can practice the rules for connecting files, which matter whichever layout you choose.

my-website/
├── index.html
├── pages/
│   └── about.html
├── css/
│   └── styles.css
├── js/
│   └── script.js
└── images/
    ├── logo.svg
    └── pattern.svg

my-website is the project folder. index.html is our homepage; many web servers use that filename as a folder's default page. The pages folder contains another HTML page. css and js hold the stylesheet and script, and images holds two pictures. Names such as css or images are conventions, not special browser commands. If you rename a folder, update every path that points into it.

See it happen: try a small change

my-site/
├── pages/
│   └── about.html ← start here
└── images/
    └── leaf.svg ← find this

Start with just two HTML files

You can practice paths before learning CSS or JavaScript. Keep index.html and about.html in the same folder and link between them. If you move about.html into a pages folder, the link from index.html becomes pages/about.html. From about.html, ../index.html goes up one folder to reach the homepage.

The larger tree in this guide shows where other files might go later. You do not need to write a stylesheet or a script to complete the HTML path exercise. The same path rules will apply when you reach those subjects.

Connect the files from your homepage

The following example belongs in index.html. You do not need to understand every CSS rule or JavaScript instruction yet: focus on how the HTML names the files it uses. A path is an address telling the browser where to look.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My website</title>
  <link rel="stylesheet" href="css/styles.css">
  <script src="js/script.js" defer></script>
</head>
<body>
  <h1>My website</h1>
  <img src="images/logo.svg" alt="My website logo">
  <a href="pages/about.html">About this website</a>
</body>
</html>

link with rel="stylesheet" loads the CSS file named by href. script loads the JavaScript file named by src; defer lets this ordinary external script run after the HTML has been parsed. An image uses src, while a link to another page uses href. These attributes hold paths, not the file contents.

From index.html, css/styles.css means enter css, then find styles.css. You can also write ./css/styles.css: ./ means the current folder. Do not include my-website at the beginning, because you are already starting inside that folder. The examples assume no base element changes the document's base URL.

Start where the reference lives

The same destination can need a different path from another file. Our about.html page lives inside pages. To reach the images folder beside pages, first go up one folder with ../, then enter images. To return to the homepage, go up and find index.html.

<!-- Inside pages/about.html -->
<img src="../images/logo.svg" alt="My website logo">
<a href="../index.html">Home</a>

Each ../ goes up one level. Work from left to right instead of guessing how many dots you need. A leading slash is different: /images/logo.svg starts at the website's root, not the current folder. Root-relative paths can be useful on a hosted site, but can break when a project lives under a subdirectory or is opened directly from disk. This exercise asks for file-relative paths so the example can move together as a folder.

An external CSS file has its own starting point for url(...). A background-image reference in css/styles.css is resolved from the css folder, even when index.html loads that stylesheet. It is not resolved from the HTML page.

/* Inside css/styles.css */
body {
  background-image: url("../images/pattern.svg");
}

Check the path before moving files

Use clear, consistent filenames such as about.html and study-notes.css. Lowercase letters and hyphens are a convenient convention. Spaces are possible in filenames, but avoiding them makes paths easier to type and share. Use forward slashes in web paths rather than Windows backslashes.

Match spelling, capitalization, and extensions exactly. logo.svg and Logo.svg may behave differently on your local computer but are different paths on many web servers. A file called styles.css.txt is not the styles.css your link requests. Check the real filename in your file manager.

When a resource is missing, identify the file containing the reference, locate its folder, and follow the path from there. Check what file the path actually names. In a running website, the browser's Network panel can help you see a missing-resource request. A broken image does not necessarily mean its folder needs to move; its reference may simply start in the wrong place.

Try moving about.html beside index.html in a copy of this example. Its paths now start one level higher. Predict which references need to change. Then move it back before starting the interactive exercise, which uses the original tree above.

Go to the source

• MDN: Dealing with files ↗
• MDN: Resolving relative references ↗

Examples are authored for Tuklas and checked with code and reference documentation. This is not a claim of independent human review. Suggest a correction.