Web Island Agency

How to create internal links in Jekyll

How to create internal links in Jekyll
How to create internal links in Jekyll

Internal linking is used to establish website architecture. If it's implemented correctly your content becomes more SEO-friendly.

Building internal links in Jekyll isn't such simple as putting <a> tag and passing direct URL to the href attribute. Of course, if you do that, the link will work, but the reason, why you should never do it, is that you have to update all the links pointing to the page manually, if the page permalink changed.

Link to pages

A more efficient way to build internal links in Jekyll is using Liquid link tag. The tag accepts a document path string as a first parameter and always renders a valid link to a page generated from the document. The file path must include the original extension.

{% link _collection/document-name.md %}
{{ site.baseurl }}{% link _collection/document-name.md %}
{{ site.baseurl }}{% link _posts/2019-03-06-post-title.md %}
{{ site.baseurl }}{% link services/index.html %}
{{ site.baseurl }}{% link /assets/documents/pal-codes.pdf %}

You choose to use {{ site.base_url }} or not depending on whether you want to generate absolute URLs.

Link to posts

If you want to generate links to posts, there is a special tag you can use. The post_url tag accepts a post path relative to the _posts directory. Also, you don't have to include the file extension.

{% post_url 2019-03-06-post-title.md %}
{{ site.baseurl }}{% post_url 2019-03-06-post-title.md %}
{{ site.baseurl }}{% post_url /folder/2019-03-06-post-title.md %}

Markdown links syntax

If you're building your pages with markdown, use the following examples to generate internal links.

[Link title]({{ site.baseurl }}{% link page/index.html %})
[Link title]({% post_url 2019-03-06-post-title %})
[Link title]({{ site.baseurl }}{% post_url 2019-03-06-post-title %})

Broken pages validation

Both link and post_url tags have built-in link validation. If the file path you specify doesn’t exist, Jekyll will fail building your website. It allows you to catch broken links and fix them before deploying a website.

Join the discussion!

The article is published under the tags

Read more articles related to the topic