Skip to content

Create cleaner urlsΒ #32

@Trust-Worthy

Description

@Trust-Worthy

Perfect β€” this is a clean static structure πŸ‘

Right now you’re using the flat file style:

about.html
contact.html
team.html
publications.html

That’s why your URLs are:

/about.html
/contact.html
/team.html

On GitHub Pages, you can’t remove .html via rewrites.

So the correct solution is:

βœ… Convert Each Page into a Folder with index.html


πŸ”§ Step 1 β€” Restructure Your Files

Change this:

about.html
contact.html
team.html
publications.html

Into this:

about/
  index.html
contact/
  index.html
team/
  index.html
publications/
  index.html

Keep your root index.html exactly where it is.


🎯 Your New Structure Should Look Like:

.
β”œβ”€β”€ index.html
β”œβ”€β”€ about/
β”‚   └── index.html
β”œβ”€β”€ contact/
β”‚   └── index.html
β”œβ”€β”€ team/
β”‚   └── index.html
β”œβ”€β”€ publications/
β”‚   └── index.html
β”œβ”€β”€ assets/
β”œβ”€β”€ CNAME
...

You are not changing the contents, just moving each file into a folder and renaming it to index.html.


πŸ”§ Step 2 β€” Update Your Links

Change links like this:

❌ Old

<a href="about.html">About</a>

βœ… New

<a href="/about/">About</a>

Do this for all internal navigation.


⚠️ Important: Project Site vs User Site

If your site is:

username.github.io

You can safely use:

<a href="/about/">

If your site is:

username.github.io/repo-name/

Then you must include the repo name:

<a href="/repo-name/about/">

Otherwise links break.


πŸ”₯ Step 3 β€” Fix Asset Paths (Very Important)

Because you’re moving files deeper into folders, relative paths like:

<link rel="stylesheet" href="assets/css/main.css">

will break inside /about/index.html.

You have two safe options:


βœ… Option A (Best): Use Root-Relative Paths

Change all asset links to:

<link rel="stylesheet" href="/assets/css/main.css">
<script src="/assets/js/main.js"></script>
<img src="/assets/images/logos/openbwc-rectangle-logo.png">

This works perfectly if:

  • You’re using a custom domain (you have a CNAME, so likely yes πŸ‘)
  • Or it's a user site (username.github.io)

⚠️ If It’s a Project Site

Then root-relative paths must include the repo name:

/assets/... ❌
/repo-name/assets/... βœ…

πŸš€ What Your URLs Will Become

Instead of:

/about.html
/team.html

You’ll get:

/about/
/team/
/contact/
/publications/

GitHub Pages automatically serves index.html inside folders.

No config needed. No Jekyll required.


πŸ’‘ Why This Works

When someone visits:

/about/

GitHub Pages looks for:

/about/index.html

That’s built into static hosting behavior.


🧠 Final Checklist

βœ” Move each .html file into its own folder
βœ” Rename it to index.html
βœ” Update navigation links
βœ” Fix asset paths
βœ” Commit & push

Done.


If you tell me whether this is:

  • username.github.io
  • or username.github.io/repo-name

I’ll tell you the exact safest linking strategy so nothing breaks.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions