GitHub Pages links returning 404

[yariv33]

Select Topic Area

Question

Body

i have a github website with two links. the site is working but when i try to press links i get 404 error. i tryed all the conventional solutions. any suggestios?

[dhrubojyotihazra]

Hey there! 👋

404 errors on GitHub Pages when navigating between links usually boil down to how GitHub's servers route and read files compared to your local development environment. Since you've already tried the conventional solutions, let's look at a few sneaky edge cases that frequently cause this:

1. The Project Site Routing Trap (Absolute vs. Relative Paths)
   If your repository is a Project site (e.g., yourusername.github.io/my-project), using an absolute path with a forward slash will break your links.

The Error:

Why it fails: The leading slash tells GitHub to look at the root domain (yourusername.github.io/about.html), completely skipping your project folder.

The Fix: Remove the leading slash to make it a relative path. Change it to or .

2. Client-Side Routing (React, Vue, Angular)
   If you built this site using a Single Page Application (SPA) framework like React, standard routing (like BrowserRouter) will fail on GitHub Pages. When a user clicks a link to /about or refreshes the page, GitHub looks for a physical folder named about with an index.html file inside it. When it doesn't find it, it throws a 404.

The Fix (Option A): Switch your router to a HashRouter. This adds a # to your URLs (e.g., yoursite.com/#/about), which prevents the browser from making a new request to the GitHub server.

The Fix (Option B): Add a 404.html file to your public directory with a script that redirects the request back to your index.html with the correct path parameters (often referred to as the SPA GitHub Pages hack).

3. Strict Case Sensitivity
   Your local Windows or Mac machine is usually case-insensitive. If your file is named About.html but your link is , it will work perfectly on your computer. However, GitHub Pages runs on Linux servers, which are strictly case-sensitive.

The Fix: Check your repository files carefully. Ensure the exact capitalization in your href matches the actual file name character for character.

4. The .nojekyll Bypass
   By default, GitHub Pages runs your code through Jekyll, a static site generator. Jekyll automatically ignores any files or folders that start with an underscore (e.g., _pages, _next, _assets). If your linked files are inside one of these folders, they won't be published.

The Fix: Create a completely empty file named exactly .nojekyll in the root of your repository and commit it. This tells GitHub Pages to bypass Jekyll and publish your folders exactly as they are.

If none of these hit the mark, could you share the link to your repository? Seeing the file structure usually makes the exact issue stand out immediately!

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[itxashancode]

Check how your links are formatted first. If you are using absolute paths like /about, GitHub Pages will look for yourusername.github.io/about instead of yourusername.github.io/repo-name/about. Switch to relative paths or set the base path in your framework config to match your repository name.

If you are using a single page application, I ran into this exact problem. Client side routers handle navigation in the browser, but a direct link or refresh hits the GitHub server. Since GitHub Pages only serves static files, it returns 404. You can fix it by switching to hash routing, or by adding a 404.html file to your repo root that redirects to index.html while preserving the route.

Are you using a client side router like React Router, or is this just plain HTML links?