I have done a lot of reading about how to use links in markdown, how jekyll allows for use of the baseurl variable, the link tag, and the liquid filters relative_url & absolute_url. None of this is working like I expected it to. I cannot find a way to write links in a format like [click here](/relative/link/here/) and that seems bizarre. I am seeing the same issues when hosting locally and when on github pages. Maybe I have something misconfigured.
Here is a test case to demonstrate:
I am using the minima theme.
In my _config.yml I have:
baseurl: "/oceanobs-rcn"
url: ""
Two files are in /docs/: test.md and test_sub.md. The page test.md demonstrates my issues. Below is the files’ content.
test_sub.md
---
layout: page
title: Test Sub Page
permalink: /test/sub
---
this is a page with unimportant content.
test.md
---
layout: page
title: Test Page
permalink: /test/
---
two files in the `/docs/` directory root:
* `test.md` with `permalink: /test`
* `test_sub.md` with `permalink: /test/sub`
-------------------
expected result `https://mysite.com/my_baseurl/test/sub`
-------------------
n | ln format | rendered ln | markdown | rendered href | note
--|----------------------------------------------|-------------------------------------|-------------------------------------------------------|---------------|-------------------
1 | raw permalink | [ln](/test/sub) | {% raw %}`[ln](/test/sub)`{% endraw %} | `"/test/sub` | missing baseurl
2 | permalink w permalink `/test` auto-appended? | [ln](sub) | {% raw %}`[ln](sub)`{% endraw %} | `"sub` | works but is horrible
3 | link tag | [ln]({% link test_sub.md %}) | {% raw %}`[ln]({% link test_sub.md %})`{% endraw %} | `"/test/sub` | missing baseurl
4 | relative_url | [ln]({{ sub | relative_url }}) | {% raw %}`[ln]({{ sub | relative_url }})`{% endraw %} | `""` | links to current page (/test/)
5 | absolute_url | [ln]({{ sub | absolute_url }}) | {% raw %}`[ln]({{ sub | absolute_url }})`{% endraw %} | `""` | links to current page (/test/)
The only one that works is # 2 and I really hate that one. I don’t understand how or why it works and I don’t want to use it. Ideally I want to use # 1 but # 3 and # 4 also make sense to me and I would be happy using them.
[Link to a page]({{ site.baseurl }}{% link test_sub.md %})
or maybe:
[Link to a page]({% link test_sub.md | absolute_url %})
#2 is a little surprising, not sure what is going on there.
For 3 and 4 I think the file extension is required.
If you look at the actual rendered html you can see that with just sub you get href="sub" which is clearly not what you want but seems to do something via some quirk in how href works.
it does seem like link should be able to use the relative or baseurl value, not sure why it doesn’t, my guess is it wouldn’t know which one you want so you have to specify it? do make for a bit of a pain to write - I would use/create a snippet in my text editor for this kind of thing.
Caveat - I don’t use link anywhere so my advise may not be that great.
If you look at the actual rendered html you can see that with just sub you get href="sub" which is clearly not what you want but seems to do something via some quirk in how href works.
Oh that is interesting. I didn’t look at the rendered html before. I assumed the links would all be as shown when clicked but none of them are links with url and baseurl. Perhaps jekyll isn’t rendering them in the html as I expected it would.
I just added a “rendered href” column to document what is in the actual html href.
The link tag and other tags does not with a filter chain.
So this is invalid
{% link test_sub.md | absolute_url %})
This is what I do for all my Jekyll 3 sites
[Link to a page]({{ site.baseurl }}{% link test_sub.md %})
In Jekyll 4, you can simply do the link tag and it will add the relative URL subpath for you.
[Link to a page]({% link test_sub.md %})
Most of the time you should not want to use absolute URLs. Use relative URLs. You will need an absolute URL for meta HTML tags, RSS feed maybe, sitemap…
I guess you could use url from config if it was set with a domain. To make this absolute.
[Link to a page]({{ site.url }}{{ site.baseurl }}{% link test_sub.md %})
In Jekyll 4, you can simply do the link tag and it will add the relative URL subpath for you.
[Link to a page]({% link test_sub.md %})
Gee. That’d be swell. Any ideas on why it’s not working for me?
Maybe I’m reading the docs for Jekyll 4 and using Jekyll 3? My gemfile.lock says 3.9.0 - I don’t know ruby but I’m assuming that’s my Jekyll version.
Thanks for the advice. Unfortunately I can’t update past 3.9.0 because that is the most recent github pages uses (ref).
Is there a good way to do relative urls in jekyll 3.9.0?
It seems reasonable to ask for [my link](/relative/url/) and it seems absolutely bizarre that [ln](url) and [ln](mysite.com/my_baseurl/relative/url) are my only two options.
I’m really happy things are better in later versions of jekyll but I need to make this work with github pages.
Again, this is what I do in Jekyll 3 and that is the best option and reasonable to do.
[Link to a page]({{ site.baseurl }}{% link test_sub.md %})
To get
[my link](/my-repo/products/popcorn.html)
So make it a habit to do that for your links. And use find and replace with your IDE to fix existing links.
If you really want to make it shorter you can make an includes file that takes title and URL as params and renders the URL inlcuding the base. But then you have to use that includes consistently wherever you have links.
You can use Netlify or GH Actions + GH Pages to use Jekyll 4. So you can use shorter syntax.
But doing that for URLs alone is maybe not worth it. Those platforms are good if you need other benefits like custom gems or Node in your flow.
Thank you! I guess I skippped over that in my first read of your reply. This seems to be working and is much better than the other two I was looking at.
Leaving a note here that in Jekyll 4 the above relative link doesn’t work, and that aligns with the Jekyll documentation on links. I have to type the full path, but specifically without the initial / for some reason:
[Link to a page]({% link docs/test_sub.md %})
# the linked file is at /docs/test_sub.md
The path to the post, page, or collection is defined as the path relative to the root directory (where your config file is) to the file, not the path from your existing page to the other page.
