Building the Jekyll site yields broken links


Currently, I am working to get a GitHub pages website working for a personal project. I am using the Doks Jekyll theme. I have no issues at all locally. However, when I commit the _site folder to my GitHub repo, the HTML it generates does not link to the folders properly. I want to be able to add markdown files and it generate the properly linked HTML.

For example, when I run the build and get the HTML for my site and look at it, the folders have to be manually updated for it to work. My Overview index file improperly points to /doks-theme/assets/css/style.css instead of …/doks-theme/assets/css/style.css (It is one folder back) the same goes for my scripts (one folder back).

Additionally, the main index file has /doks-theme/assets/js/vendor/jquery.min.js but I need to remove the “/” for it to work. I’m wondering if I just have something set up wrong?

Like I said, I can get it working but im pretty sure manually doing this is not the proper method. Here is the folder containing the source files. I have things structured in a way where the site works right now and inside the local folder I have my local build with the _site folder.

Repo: at main · Joshua-McGee/ · GitHub

Steps I’ve taken so far:

  • I already updated my config.yml to contain baseurl
  • In the MD files for the new webpages ive properly set the url values to go back to the proper folders.

Chances are you have not set the _config.yml file’s url and baseurl Settings?

I have set both of those in my config.yml file hence why im confused.

Odd. I downloaded your repo to my local machine and it ran, so then I did a test of pushing it up to a new Jekyll repo in GitHub and it still seems to work.

Take a look here and let me know if there is a specific page that is not working?

Yes, currently the repo as-is will run because I manually modified the root folder HTML and how they link (to confirm that was the issue).

If you were to try going into the local folder (where the markdown and all that is) and then run Jekyll build which updates the _site folder (where it compiles the HTML). That folder in theory should work out of the box (if i copy paste say the index.html) but it doesnt. In other words, try copy pasting the entirity of the _site folder into main and it breaks all the links to everything.

just at a glance your repo is confusing - the main repo seems to be a jekyll project and then the local folder is also a jekyll project? and you are committing the site folder?

normally you would not commit the site folder as GH will compile that from the source. Or if you want to just host the site folder you upload it by itself without the source.

If the local folder is its own jekyll site have you tried just creating a repo for just it? I’m not sure what GH will do with a jekyll site inside a jekyll site, seems problematic.

@digitalcontent Jekyll is designed to generate files meant to be served by a webserver.
The generated site cannot be navigated through without a webserver.

I created a different repo with the problem for everyone to look at here: GitHub - Joshua-McGee/doks: documentation website testing

I attempted to set the source as the /docs folder.

How might I do that with Github pages? I’m not sure I fully follow, I’m a little new and self-taught for a lot of this.

when you see the problem, how are you viewing the web page? just by right clicking on an index file and opening it in the browser?

that will likely not work as there is no server involved to properly get the paths to your css/js to work.

You need to use Jekyll serve to see if things work, or load the website up to a web server.

Its hard for us to know what you are looking at - if it is all local. If you can put a link to a page that is publicly available on the internet that shows the problem then that would help a lot.

Agenda here is it being served via GitHub pages

First of all, you’re over-complicating things.
Secondly, decide whether you want GitHub to build your Jekyll site at root of repository or within the docs/ directory.

In the new test repo doks, you have configured GitHub Pages to build the docs/ folder. But FYI, there are multiple docs sub-directories in your repository.
Regardless, GitHub Pages will build your top-level docs and deploy automatically as long as there is no _site directory within.
Just wait for some time.

Your test repository aside, to deploy a site via GH Pages, all you need to do is:

  • start locally by running jekyll new <PATH>
  • Ensure that _site and .*-cache folders are gitignore-d.
  • Make desired changes, commit, and push to GitHub repository.
  • Wait for GitHub to build the repo at root.

in your head include doks/site-head.html at main · Joshua-McGee/doks · GitHub for the css you have

<link rel="stylesheet" href="{% if jekyll.environment == 'production' %}{{ site.doks.baseurl }}{% endif %}/doks-theme/assets/css/style.css">

I think it should just be site.baseurl not site.doks.baseurl

If that works then you have the same thing in the footer include for the scripts.

Ok, I think I understand where things might be going wrong. I was under the impression that I have to run Jekyll build and upload the _site folder contents to GitHub. I did not understand that GitHub Pages compiles all this automatically.

This means @ashmaroli was correct and I overcomplicated things.

I set the repo to root, made sure gitignore was correct, and removed the _site and docs folder then let github build it. I think I should be able to take it from here now that I understand how things work.

Thanks a ton all! and for anyone having this problem start by making sure the config.yml is setup properly because I’ve read thats where most ppl go wrong. If thats setup github should be able to build everything without you needing to do anything with the _site folder which is honestly not needed for github pages.

Good news! FYI, I created a playlist that teaches GitHub Pages and Jekyll basics. Here is the start of the short series if you are interested:

1 Like