Website Folder Structure: HTML, CSS, JS and Images
November 11, 2026 · 9 min read
Website Folder Structure: Organize HTML, CSS, JS and Images
A good website folder structure puts index.html at the root and gives CSS, JavaScript and images their own folders. Name files in lowercase with hyphens. Link them with paths relative to the page that loads them, and your links survive moving the project or uploading it to a host.
A Starter Website Folder Structure You Can Copy
For a one-page or few-page static site, this is all you need:
my-site/
├── index.html
├── css/
│ └── style.css
├── js/
│ └── main.js
└── images/
├── logo.svg
└── hero.jpg
Here's what each part does:
my-site/is the project root. Everything the site needs lives inside it, and it's the folder you upload.index.htmlis the home page. Most web servers serve this name by default when someone requests a folder.css/holds stylesheets. Onestyle.cssis enough until it grows past a few hundred lines.js/holds scripts. Leave it out if the site has no JavaScript.images/holds photos, icons and logos.
There's no single official layout. MDN's beginner guide to dealing with files names the folders styles, scripts and images, while plenty of projects use css and js. Pick one naming scheme and keep it. To sketch your own tree before you build it, the directory tree generator turns an indented list into a drawing like the one above. For a folder that already exists, our Linux directory tree guide shows how the tree command prints one.
Why Does index.html Go at the Root?
Web servers serve a default file when someone requests a folder instead of a file. Apache's mod_dir documentation lists DirectoryIndex index.html as the default, and nginx's index directive also defaults to index.html. So a visitor who types your domain gets index.html without seeing the file name.
GitHub Pages works the same way. It looks for an index.html, index.md or README.md file at the top of your publishing source and uses it as the entry page.
The rule also applies inside subfolders. Put an index.html inside about/ and the page answers at /about/ instead of /about.html. That's how static sites get clean URLs without any server configuration.
How Should You Organize HTML, CSS and JavaScript Files?
Keep each file type in its own folder and keep HTML pages where their URLs should be. The home page and top-level pages sit at the root or in their own subfolders, while supporting files go in css/, js/ and images/. A fonts/ folder joins them if you self-host web fonts.
The home page then links its supporting files like this:
<link rel="stylesheet" href="css/style.css">
<script src="js/main.js" defer></script>
<img src="images/logo.svg" alt="Site logo">
Each path starts from the folder that holds index.html, so css/style.css means: go into css, then load style.css. Use forward slashes even on Windows, since URLs always use them.
As a site grows, you might split CSS into a shared base.css plus one file per page type. Keep the split small. Three or four stylesheets are easier to reason about than one per page.
Relative, Parent and Root-Relative Paths Explained
Many broken links in a web folder structure come from paths that only work from one location. A path is resolved from the URL of the file that contains it. MDN's guide to what a URL is covers the rules. Here's what each style does when you write it inside blog/index.html, served at https://example.com/blog/:
| Path written | Resolves to | Opened from disk |
|---|---|---|
css/style.css | example.com/blog/css/style.css (wrong folder) | Fails |
../css/style.css | example.com/css/style.css | Works |
/css/style.css | example.com/css/style.css | Fails |
https://example.com/css/style.css | That exact URL | Works if online |
../ means go up one folder, and you can chain it: ../../images/logo.svg climbs two levels. A leading slash means start from the root of the domain, ignoring where the current page sits.
Root-relative paths are tidy because every page uses the same string. They break in two common cases, though. Opened straight from disk with file://, a leading slash points at the root of your drive, not your project folder.
On a GitHub Pages project site, which lives at owner.github.io/repository-name, /css/style.css points at the account's root and skips the repository folder. The About GitHub Pages page lists both URL patterns. Plain relative paths work in both cases, which is why we default to them.
One more subtlety: the trailing slash matters. Relative paths in a page loaded as /blog resolve from the root, while the same page loaded as /blog/ resolves from inside blog. Apache's default DirectorySlash On setting redirects the first to the second, and its docs list working relative links as one of the reasons.
Why Is My CSS or Image Not Loading?
When a stylesheet or image silently fails, the cause is usually a path or name mismatch. Work through this checklist:
- Open your browser's developer tools, switch to the Network tab and reload. A missing file shows a 404 status and the exact URL the browser tried.
- Compare that URL with where the file really sits. Paths in HTML resolve from the HTML file, not from your project root.
- Check
url()inside CSS. A background image path incss/style.cssresolves from the stylesheet, so it needs../images/hero.jpg, notimages/hero.jpg. - Check the case.
Logo.PNGandlogo.pngare different files on most web servers. - Look for spaces in names. They become
%20in URLs and are easy to mistype. - If you use root-relative paths, preview through a local server instead of double-clicking the file.
Here's the url() case from step 3, written inside css/style.css:
.hero {
background-image: url("../images/hero.jpg");
}
The ../ climbs out of css/ to the project root, then goes down into images/. For a quick local server, run python3 -m http.server in the project root and open http://localhost:8000.
File Naming Rules That Prevent Broken Links
Names are part of your URLs, so they deserve the same care as the folders. These rules build on MDN's guidance:
- Lowercase everything. MDN notes that most web servers are case-sensitive. The default file systems on Windows and macOS usually aren't, so a wrong-case link can work on your laptop and 404 after upload.
- Use hyphens between words.
contact-form.htmlreads well in a URL. Avoid spaces and underscores. - Skip special characters. Stick to letters, digits, hyphens and dots.
- Keep names stable. Renaming
about.htmlbreaks every link and bookmark pointing to it, so choose descriptive names early.
Descriptive image names pay off too. blue-ceramic-mug.jpg tells visitors and search engines far more than IMG_2847.jpg.
Growing to a Multi-Page Site Folder Structure
Once you have more than a handful of pages, give each page its own folder and group the supporting files under assets/:
my-site/
├── index.html
├── 404.html
├── favicon.ico
├── robots.txt
├── about/
│ └── index.html
├── blog/
│ ├── index.html
│ └── first-post/
│ └── index.html
└── assets/
├── css/
│ └── style.css
├── js/
│ └── main.js
├── images/
└── fonts/
A few files sit at the root on purpose. When a page has no icon link, the HTML standard lets browsers request /favicon.ico from the site root, though an explicit icon link is safer. Crawlers look for robots.txt only at the root of a host. GitHub Pages serves a 404.html from the publishing source when a page is missing, and many other static hosts follow the same convention.
We prefer a single assets/ folder at this point. It keeps the root short enough to scan, and every page can reach shared files with one predictable path. The trade-off is depth: blog/first-post/index.html needs ../../assets/css/style.css, which is where root-relative paths start to look attractive if your host serves the site from the domain root.
Keep working files out of the folder you upload. Layered design files, notes and a README.md can live one level up, beside my-site/, so they never end up on the public server. If you deploy from a Git repository, check which folder your host publishes before you add extra files.
This layout is for hand-built static sites. Frameworks such as Next.js, and static site generators, impose their own conventions with separate source and output folders, so follow their docs instead. Our Next.js folder structure guide covers that framework's layout.
Where Markdown Fits in a Static Site
You don't have to write every page in raw HTML. Many people draft content in Markdown and convert it, and our post on Markdown vs HTML explains what each format is good at. The Markdown to HTML converter runs in your browser and returns one complete HTML document. You put that HTML into the right folder yourself, for example as about/index.html.
For other conversion routes, see how to convert Markdown to HTML. If your pages include images, the same relative-path rules apply inside Markdown, as in this line in blog/first-post/index.md:

That renders as the logo once the converted page sits two folders below the root. Our guide to Markdown images covers the rest of the syntax.
Frequently Asked Questions
A tidy website folder structure comes down to three habits. Keep index.html at the root, give each file type its own folder, and use lowercase names with paths relative to the page that loads them. Test with a local server before you upload, and check the Network tab whenever something goes missing. When you plan the next section of your site, sketch it first with the directory tree generator.