Multi-file HTML projects: entry pages, relative paths and local assets

What is a multi-file HTML editor?

A multi-file HTML editor preserves a project as separate documents and assets instead of combining everything into one HTML string. One HTML file acts as the preview entry point—usually `index.html`—and its relative URLs connect stylesheets, scripts, images, fonts and other pages. The editor needs a file tree, a way to identify the active entry page and a browser-accessible URL for each project resource. Moving or renaming a file can change the correct relative path, so a reliable editor updates references or clearly reports missing files. This model is closer to a static website served from a folder than a single-snippet playground, but it still has boundaries: server rewrites, package imports, backend routes and build-time transformations are not created automatically. Use it when the folder structure is meaningful, then test the exported project on the host that will actually serve it.

A predictable project structure

project/
├── index.html
├── css/
│   └── styles.css
├── js/
│   └── app.js
└── images/
    └── logo.webp

From `index.html`, the correct references are `css/styles.css`, `js/app.js` and `images/logo.webp`. From `css/styles.css`, a background image in the images folder is reached with `../images/logo.webp` because the stylesheet lives one directory deeper. The URL resolution algorithm follows the document or stylesheet URL, not the visual position of a file in an editor sidebar.

Choose and protect the entry HTML

Static hosts conventionally serve `index.html` for a folder, so it is a sensible automatic default. A project may still contain demonstrations, documentation or nested pages. Selecting the preview entry explicitly prevents the editor from switching to the last HTML file merely because it was clicked. When an entry is renamed or deleted, the preview should either update the selection or present a clear missing-entry state.

Relative, root-relative and absolute URLs

• Relative: `images/photo.jpg` starts from the current document directory.
• Parent-relative: `../images/photo.jpg` moves up one directory first.
• Root-relative: `/images/photo.jpg` starts from the web origin root, which may differ from the virtual project root.
• Absolute: `https://example.com/photo.jpg` requests another complete URL and requires a network connection.

The MDN guide to URLs explains the components and resolution model. Prefer relative URLs for portable static projects that may be moved between folders or hosts.

Images, fonts and binary files

Text files can be edited directly. Binary assets should stay as byte data or browser blobs; interpreting them as text corrupts the file. A preview can expose a temporary URL for the asset, while an export writes the original bytes back into the ZIP or embeds them as data URLs in a single-file build.

Use descriptive filenames, correct extensions and consistent case. Add width and height to content images when dimensions are known so the browser can reserve space and reduce layout shift. Use `alt=""` for decorative images and meaningful alternative text for images that communicate information.

Renaming and moving files safely

1. Identify references in HTML attributes such as `src`, `href`, `poster` and `srcset`.
2. Inspect CSS `url(...)` and `@import` references.
3. Calculate the new path from each referring file, not from the project root alone.
4. Refresh the preview URL or invalidate its asset cache.
5. Verify navigation, images, fonts and scripts before exporting.

Why a local folder may behave differently

Opening `file://` URLs bypasses a normal HTTP origin and triggers browser restrictions around modules, fetch requests, service workers and cross-origin access. A project preview served through a local or virtual HTTP URL behaves more like a static host. For final testing, use a small local server or the actual deployment preview instead of relying only on double-clicking `index.html`.

What the editor does not manufacture

A folder containing React, Vue, TypeScript or Sass source usually needs a build step. Bare package names such as `import React from 'react'` are resolved by tooling, not by a plain browser folder. A multi-file static editor works best with browser-ready HTML, CSS, JavaScript and assets. If a framework has already produced a static `dist` directory, that output can often be previewed as a normal project.

Common path mistakes

A leading slash can accidentally point to the editor's host root instead of the imported project root. A stylesheet can resolve images from its own folder while a developer expects paths to start from `index.html`. URL-encoded spaces, query strings and fragments can hide the true filename during a quick visual check. Renaming only the visible file label without updating references creates another subtle failure. When in doubt, copy the failing URL from the browser console, compare every path segment with the file tree and calculate the relative path from the file that contains the reference.

Next: prepare a portable archive with the ZIP import and export guide.