Files and paths

How should you name files and folders?

Use lowercase letters, numbers and hyphens in file names, and nothing else. opening-hours.html and img/sourdough-loaf.jpg are safe on every server, in every URL and in every command line. Spaces become %20 in addresses and break when someone copies a link from an email. Accented letters and symbols such as &, # and ? have special meaning in URLs or get encoded in ways that differ between systems.

Hyphens are preferred to underscores because search engines treat hyphens as word separators, and underscores disappear under link underlines. Keep names short and descriptive. A file called IMG_4821.JPG tells nobody, including you in six months, what it shows.

Group files by type or by section. A small site can use css/, js/ and img/ folders next to the pages; a larger one might add events/ or blog/ folders for groups of pages.

bird-club/
  index.html
  events.html
  join.html
  css/site.css
  img/robin.jpg
  events/
    dawn-chorus.html

Why is index.html loaded automatically?

When a URL ends in a folder, such as https://example.org/events/, the web server looks for a default file inside it. On almost every host that file is index.html. That is why your home page should be named index.html and why /events/ can be a clean URL for events/index.html.

If no index file exists, the server either shows a 404 error or, if directory listing is switched on, a list of every file in the folder. That list can expose drafts and backups you never meant to publish. Add an index file to every folder that should be reachable, or turn off directory listing in the host settings.

Opening a local file with a double-click does not use a server, so index.html gets no special treatment there. A link to events/ will show your computer's folder view instead. Use a small local server, such as the Live Server extension in VS Code or python3 -m http.server, to test folder URLs the way they behave online.

When do you need an absolute URL?

An absolute URL includes the scheme and host: https://rspb.org.uk/birds/robin. Use one whenever you link to another site. The https:// part is required. Without it, www.rspb.org.uk is read as a relative path to a file with that name on your own site, and the link breaks.

Some places require absolute URLs even for your own pages. The <link rel="canonical"> tag, Open Graph images in <meta property="og:image">, sitemap entries and links in emails all need the full address, because they are read outside the context of your page.

Avoid http:// for anything you load into the page. Browsers block or upgrade insecure images and scripts on HTTPS pages, which shows as mixed content warnings in the DevTools console.

<a href="https://www.rspb.org.uk/birds-and-wildlife/robin">RSPB robin guide</a>
<meta property="og:image" content="https://birdclub.example/img/share.jpg">

How does the browser resolve a relative path?

A relative path starts from the folder of the current page. If the page is /events/dawn-chorus.html, then map.jpg means /events/map.jpg, img/map.jpg means /events/img/map.jpg, and ../img/robin.jpg steps up one folder to /img/robin.jpg. Each ../ climbs one level. Writing ./map.jpg is the same as map.jpg.

Paths inside CSS files are relative to the CSS file, not to the page. A rule in /css/site.css that says url(img/bg.jpg) looks for /css/img/bg.jpg. Use url(../img/bg.jpg) or a root-relative path.

Relative paths make a site portable. You can move the whole folder to a new domain, or preview it locally, and the links still work. The cost is that moving a single page into a different folder breaks its paths, so update them when you reorganise.

<!-- On /events/dawn-chorus.html -->
<img src="../img/robin.jpg" alt="Robin singing">
<a href="../join.html">Join the club</a>

What does a leading slash do?

A path starting with / is root-relative. It always starts at the top of the domain, whatever page it sits on. /img/robin.jpg points to the same file from the home page and from a page five folders deep, which makes it handy for shared headers and navigation.

Root-relative paths have two catches. They do not work when you open files directly from disk, because / then means the root of your hard drive. And they break when a site lives in a subfolder, such as a GitHub Pages project at username.github.io/bird-club/, where / points to username.github.io/ and misses the project folder. In those setups, use relative paths or configure your site generator's base path.

A path starting with // is protocol-relative. It was a workaround from the HTTP to HTTPS transition and is now legacy; write https:// instead.

Why does a path work on your laptop and fail on the server?

Windows and the default macOS file system ignore letter case, so Robin.JPG and robin.jpg are the same file on your laptop. Most web servers run Linux, where they are two different names. A mismatch works perfectly during development and returns 404 after upload. Lowercase-only naming removes this problem for good.

The other usual causes are a path pointing at your own disk (C:\Users\... or file:///), a file that never got uploaded, backslashes copied from Windows Explorer instead of forward slashes, and spaces in names that were encoded differently by an upload tool.

How do you track down a broken path?

Open DevTools, go to the Network panel and reload. Failed files appear in red with a 404 status. Click one to see the full URL the browser requested, then compare it with where the file actually is. The difference is nearly always a missing ../, a case mismatch or a wrong folder name.

In the Elements panel, hover over an src or href value to see the resolved absolute URL. The console also lists failed loads with their URLs.

When reading AI-generated code, check paths before anything else. AI tools guess folder names such as assets/images/ or static/ that do not exist in your project, mix root-relative and relative styles, and sometimes leave placeholder paths like path/to/image.jpg. Search the output for src= and href= and confirm each target exists.

Field notes

• Name files with lowercase letters, numbers and hyphens only.
• A relative path starts from the folder of the current page.
• Each ../ in a path moves up one folder.
• A path starting with / always begins at the top of the site.

Easy to get wrong

Local disk paths only work on your own computer. Use paths relative to the page.

Without the scheme the browser treats it as a relative path to a file named www.example.com.

Servers are usually case-sensitive, so the mismatched name returns a 404.

Paths in a stylesheet resolve from the stylesheet's folder, so the first version looks in /css/img/ and finds nothing.

Spaces and capitals make fragile URLs that break when copied, shared or moved to a case-sensitive server.

Questions people ask

What is the difference between / and ./ in a path?

/ starts at the root of the domain. ./ starts at the current page's folder, which is the same as writing no prefix at all.

Why does my image show locally but not online?

The usual causes are a case mismatch in the file name, a path pointing to your own disk, or a file that was not uploaded.

Should I use .html or .htm?

Use .html. Both work, but .htm is a leftover from systems limited to three-letter extensions.

Do I need index.html?

You need it if you want a folder URL like example.com/ to show a page. Without it, the server may show an error or a file listing.

Why do my root-relative links break on GitHub Pages?

Project sites live in a subfolder, so / points to the user root, not your project. Use relative paths or set a base path in your site generator.

Can I link to a file on my own computer?

Only for your own testing. Paths like file:/// or C:\ point at your disk and fail for every visitor.