Why static GitHub deploys break and how we can (usually) resolve them with a quick refactor.

When we deploy a static website to GitHub Pages, the build process will search for the index.html file inside of the root directory. e.g my-project/index.html

If GitHub cannot locate the ~/index.html it will default to the readme file if present.

✅ Correct Directory Structure

Here is an example to help visualize the correct directory structure.

Repo
├── ... other files/sub-folders
├── index.html
└── README.md

❌ Incorrect Directory Structure

Here is an example of an incorrect directory structure.

Repo
├── ... other files/sub-folders
├── README.md
└── sub-folder/
    └── index.html

*Caution before redeploying, check the local version and ensure everything works! We might need to update some relative paths in our directory.*

Once we are able to confirm everything works locally we can push these changes to GitHub and we should be able to see the website! 🤞

git add .
git status

git commit -m 'resolved deploy'
git push origin main