How the builder picks the start page
When a ZIP is uploaded, the builder decides which page the app opens with, in this order:
index.htmlat the top of the archive, if there is one;- otherwise, if everything sits inside one folder, that folder's
index.html— the folder is stripped off, which is why "I compressed the folder instead of its contents" usually just works; - otherwise, the shallowest HTML file it can find.
Rule three is where things go wrong. Zip a whole framework project and the shallowest HTML file is the index.html template in the project root — which loads uncompiled source and shows a blank page — not the real one in dist/. Zip a repository with a docs/ site and a demo/ page and you get whichever path is shorter. Flattening removes the guesswork: the page you choose becomes the only candidate.
The three ways a ZIP ends up nested
| How it happened | What the archive looks like | Pick this folder |
|---|---|---|
| You compressed the folder rather than its contents | my-site/index.html | my-site/ |
| You zipped a whole framework project | my-app/src/…, my-app/dist/index.html | my-app/dist/ (or build/, out/) |
| You downloaded a repository from GitHub | repo-main/docs/index.html | the folder GitHub Pages served |
When a project ZIP contains both the source and a build folder, this tool pre-selects the build folder (dist, build, out, public, www, docs). The source index.html of a Vite or React project is a template that loads uncompiled code; the app needs the compiled one.
What gets copied
Everything inside the folder you pick, with its internal structure unchanged, so every relative link in your pages keeps working. Anything outside that folder — the source code, package.json, the README — is left out. File dates are preserved. Nothing is uploaded: the new ZIP is assembled in this tab and downloaded directly.
Doing it by hand next time
Open the folder that contains index.html, select everything inside it (Ctrl/⌘ + A), and compress the selection. On the command line: cd dist && zip -r ../site.zip . — the trailing dot is what keeps the folder name out of the archive.