Issue w/ GitHub Pages & local host


I successfully deployed my Jekyll site on GitHub (GH) pages by adding the GH repo name to the “baseurl” setting in the _config.yml file.

The issues I’m running into are:

Local host not serving - after adding the GH repo name to baseurl config setting, the repo name is getting appended to the local host (e.g. localhost:4000[GH-repo-name])and not serving after running command jekyll serve. When I remove the GH repo name from the baseurl config setting, the local host goes back to normal and works fine after running jekyll serve.

Media assets not showing on GH pages hosted site - in order to get my site to publish on GH pages I have added the GH repo name to the baseurl config setting. However, after doing this I noticed that my media files like images and favicon are not showing up, in their place is a broken link placeholder image.

Can anyone help me figure out how to 1) get my site to serve to local host and GH pages without having to change the baseurl everytime and 2) how to get my media assets to show up on the GH pages hosted site?

Thanks so much,

It’s hard to see what’s going on without file samples or a repo.

Set your base URL with a forward slash at the start not end.

Run Jekyll serve.

Go to the URL including forward slash.

For me


Try setup my project locally or using jekyll new to make a new site so you have a working point.

1 Like

As you have observed.

in HTML, that this would break on a subpath repo.


But this approach would work


This is achieved with the following.

When you have baseurl set, you can use it in your site so assets and other links are correct.

Hacky way

href="{{ baseurl }}/styles.css" 

More elegant way.

href="{{ '/styles.css' | relative_url }}" 

If you file is style.css or in assets/styles.css , you won’t know until you view the site.

An even better way is to use the link tag to get the path to a file and it will give you an error if the path is invalid so you can fix it. And so bad code is not deployed.

href="{{ site.baseurl }}{% link styles.css %}" 

Note lack of quotes on argument for link.

Unfortunately you need the baseurl approach as relative URL doesn’t work with link.

For Jekyll 4 (not standard on GH pages) you can simply do this and will add the subpath for you.

href="{% link styles.css %}" 

For dynamic values, pulled from for loop or frontmatter or something.

href="{{ page.url | relative_url }}" 

This worked beautifully! Thank you :slight_smile:

1 Like

I added the path manually and it worked. I’m new to web development and programming so I’m still working out your more advanced solution. Will report back. Thanks again.

Great. Yeah I wanted to start with the easy to understand solutions and then move up to more elegant and advanced solutions when you are ready.

1 Like

Hi Michael,

I was able to implement your elegant solution w the relative_url tag in my new build. Local host and gh page both working great.

Here’s the live page link:

Just wanted to reach out and say thanks again!

1 Like

Hi @MichaelCurrin hope all is well. I’ve circled back to this project and am once again running into url issues. I added a navigation includes linked to a data file and for now am using index.html and monster-dex.html as the link value, but this isn’t ideal and I know is not the best approach. It also break my link styling logic seen below. I also tried using variables in the data navigation yml file, but that threw a build error.

<a href="{{ }}" {% if page.url == %} class="current" {% endif %}>{{ }}</a>

I also created a home-btn includes with href="{% link index.html %}" which appears to work when navigating from page to page, but breaks when navigating from a post.

What is the best approach to get my urls to work properly while on development server and when deployed?

Here is repo link for reference:



A new topic would have been better but anyway here

Make sure you understand relative URLs in a browser.

If you are on /abc/def.html or a post /21/05/01/title.html and you use a link without a forward slash it will break.

I’m sure when you linked ‘index.html’ on a post you ended up on ‘/21/05/01/index.html’ and you should note this down for your debugging and also bring it up in your answer.

I looked at your _site (which is meant to be ignored on GitHub and deleted now) and your post does indeed this this link

    <a href="index.html" >☠️ Home</a>

When this would be a relative url that will work from anywhere.

     <a href="/index.html" >☠️ Home</a>

Even better if just “/”.

The problem is this

You need should add a forward slash to your config values flanaess-fables/navigation.yml at gh-pages · adamlevoy/flanaess-fables · GitHub

/index.html # or just "/"

Then it will also match up with page.url which includes the forwardslash.

Additionally you need to make your site work on a remote GH Pages environment.

Set up your config so you can test locally close to production. I see you have that already

Then actually use the value in your links.

This will make the url /my-repo/index.html.

href="{{ | relative_url }}"
1 Like

As to where to use that approach or the link tag.

I prefer the link tag as it will tell me at build time if a link is broken to avoid pushing bad code.

href="{% link index.html %}"

OR this is also valid.

href="{% link index.html %}"

Note no quotes.

The trick is for Jekyll 3 on GH Pages you also need to add the baseurl yourself, where relative_url filter won’t work.

href="{{ site.baseurl }}{% link index.html %}"

This is verbose but it is effective as it gives you security on valid links and works on a GH Pages subpage.

The next tricky part is what to do when the page is a variable.

When doing the for loop, you can stick to relative_url approach in my answer above assuming your navbar will be tediously maintained to make sure all the links match up as pages change.

A safer approach is to use a Liquid variable inside the tag. I have got this to work before, hopefully it was this context. Otherwise I don’t know what the correct way is

href="{{ site.baseurl }}{% link {{ item.url }} %}"

My Cheatsheet

Thank you, this was very helpful. I went with the relative_url approach and got it to work. Your cheatsheet is a fantastic resource, thank you for that.

I also went ahead and deleted the _site directory, thanks for the heads up on that as well.

I’ll make sure to start a new thread next time :slight_smile:

1 Like