index.html at the root
This is the single most common failure. You select the site folder, right click and compress, and the archive now contains one directory with everything inside it.
The server looks for index.html at the top of the archive. It finds a folder instead, and you get an empty page.
Open the archive before uploading and confirm that index.html is the first thing you see, with css, img and js beside it rather than one level down.
Every path relative
An absolute path like /css/style.css assumes the site is at the root of a domain. A site published under a path loses everything referenced that way, which produces the unstyled version of the page.
- css/style.css works from index.html at the root.
- ../css/style.css works from a page one folder down.
- /css/style.css assumes the root of the domain and is the one to remove.
- Absolute URLs to your own old domain will still work but will keep serving the old site, which is worse than breaking.
Search the files for href="/ and src="/ before you compress. It takes seconds and catches the whole class.
Filename case has to match
Windows and macOS are usually case insensitive. Web servers generally are not.
A page referencing img/Logo.png when the file is called logo.png works perfectly on your machine and shows a broken image everywhere else. This is the bug that produces the phrase but it works locally.
The habit that avoids it entirely: lowercase every filename, always, with hyphens rather than spaces or underscores.
Leave the junk out
Archives created from a desktop tend to carry passengers.
- System files such as .DS_Store and Thumbs.db.
- Editor folders such as .vscode and .idea.
- Source files that are not part of the site, such as .psd or .sketch originals.
- A node_modules folder, which is almost always larger than the entire site.
- Anything with a credential in it, which should never have been in the folder to begin with.
The upload panel lists which file types are allowed inside the archive. Checking that list once saves a rejected upload.
Look at the media before you compress
Static sites are fast until somebody drops a twelve megapixel photograph straight off a camera into the hero section.
Resize images to the size they are actually displayed at, roughly twice that for high density screens, and save them as compressed JPEG or WebP. A hero image should be a few hundred kilobytes, not eight megabytes.
Fonts are the other quiet weight. Two families and two weights each is plenty for one page, and system fonts cost nothing at all.
After publishing, open it properly
- Open the live address in a browser you have never opened the local copy in, so nothing is cached.
- Check the page on a phone, which is where most visitors will see it.
- Click every link, including the ones in the footer.
- Confirm the address bar shows HTTPS with no warning.
- Read the page once as though you had arrived from a search result.
Five minutes, and you find the broken thing before a customer does.