Jekyll and link to internal files: page not found

Help
1

I am building my website (published with GitHub Pages) and I would like to do the following: inside one of the main pages (a .md file) I would like to insert a link to another .md file, so that I can organize my projects nicely.

The current structure of the directory is the following:

  • _research_projects/project1.md
  • _congif.yml
  • all_projects.md

In the file all_projects.md I want to insert a link to _research_projects/project1.md . Therefore I inserted in the first file the following:

[Project 1](/_research_projects/project1.md)

The file project1.md contains just the following at the moment:

---
layout: default
---

This is a test!

In the file _config.yml I added the following:

gems:
  - jekyll-relative-links

relative_links:
  enabled: true
  collections: true

But it still does not work: while in the GitHub repository the link works (it goes to the file _research_projects/project1.md if I click on the link), if I click on the link from the .github.io webpage, I get the error message:

Whoops, this page doesn't exist.
Move along. (404 error)
2

try it without the _ like [Project 1](/research_projects/project1.md)

folders with an underscore are not usually output to the site folder - assuming it is a collection it is probably in the site folder without the leading underscore.

If you are building locally you should check to see what it is in the site folder.

1 Like
3

An underscore in front on a directory name is fine in the case of a collection, otherwise it should not have an underscore.

But since it works locally that isn’t your problem.

I suspect you are using a subpage domain and left that part out of your question.

e.g.

Given homepage

Username.github.io/my-repo

Then you are referencing

/_research_projects/project1.md

ie

Username.github.io/research_projects/project1.html

Which is not valid.

Fix

Two things.

First set config file to match your remote environment

e.g.

url: myuser.github.io
baseurl: /my-repo/

The URL will only be used locally for prod builds and for things like sitemap. But baseurl will be used on every build or server.

The link will be shown as server started on

http://localhost:4000/my-repo/

Then second thing is to make your URL into a relative URL.

[Project 1]({{ '/_research_projects/project1.md' | relative_url }})

There is still the chance your URL is bad like a typo or the page moves.

But this is safer as it will give an error at build / server start:

[Project 1]({{ site.baseurl }}{% link _research_projects/project1.md %})

Note no quotes in 2nd case.

And then your result will be a link like this:

Username.github.io/my-repo/research_projects/project1.html

Including the subpath.

Relative links

I see you have this plugin set up and it is used on the remote set up. I don’t think it does anything relevant to this question.

Tips

BTW for SEO it is better to use hyphens as Google crawlers splits items by hyphens but seems underscore terms as a whole word.

So

research-projects/project1.md

Also make sure you are using Jekyll 3 set in Gemfile to match GitHub Pages environment. Jekyll 4 handles the link tag differently so you’ll get weirdness if you use Jekyll 4 locally and Jekyll 3 on the remote.

1 Like