174

Jekyll uses Markdown-formatted links, but how can I link to internal content?

[[link]] 

8 Answers 8

287

You can now post internal links by using the following:

[Some Link]({% post_url 2010-07-21-name-of-post %})

This is also referenced in the Jekyll Documentation.

https://github.com/mojombo/jekyll/pull/369

6
  • 18
    Any idea how to internally link to a page?
    – Dogweather
    Nov 8, 2012 at 1:54
  • 2
    Looks like it is not possible to link to a page. This PR was closed without being merged: github.com/jekyll/jekyll/pull/369
    – northben
    Mar 25, 2014 at 20:40
  • 1
    Is it possible to get the title to show easily, e.g. render to [Title of post](/correct/permalink) with a single command? I could only do it with filtering which is too verbose. Dec 3, 2014 at 16:50
  • If you have subdirs: [Link's Text]({% post_url /dirname/2010-07-21-post %})
    – alexsalo
    Jun 12, 2015 at 20:20
  • Just a small note: do not include the extension in 2010-07-21-name-of-post.
    – teardrop
    Apr 14, 2017 at 19:44
75

It is now possible to link to pages other than posts using the link tag. link works for posts, pages, documents in a collection, and files.

{{ site.baseurl }}{% link _collection/name-of-document.md %}
{{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %}
{{ site.baseurl }}{% link news/index.html %}
{{ site.baseurl }}{% link /assets/files/doc.pdf %}

Remember to include the file extension when using the link tag. To use it to create a link:

[Link to a document]({{ site.baseurl }}{% link _collection/name-of-document.md %})
[Link to a post]({{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %})
[Link to a page]({{ site.baseurl }}{% link news/index.html %})
[Link to a file]({{ site.baseurl }}{% link /assets/files/doc.pdf %})

See Jekyll Documentation.

3
  • 3
    I also found this documentation page helpful - jekyllrb.com/docs/liquid/tags/#link Oct 16, 2018 at 9:37
  • 3
    I've just found that there is no need to use {{ site.baseurl }} since it doubles baseurl value in the generated href. [Link to a post]({% link _posts/2016-07-26-name-of-post.md %})
    – oleksa
    Oct 31, 2019 at 12:09
  • 4
    You need to use site.baseurl on Jekyll 3.x, it is no longer needed in 4.x. But Pages is still stuck on 3.x as the max version, AFAIK. Jun 17, 2020 at 21:42
26

For pages, they decided not to add a page_url tag because you'd have to know the path of the page anyway. So you just have to link to it manually:

[My page](/path/to/page.html)

Or you can do something big and ugly like this if you want to programatically get the title of the page:

{% for page in site.pages %}
  {% if page.url == '/path/to/page.html' %}
[{{ page.title }}]({{ page.url }})
  {% endif %}
{% endfor %}
1
  • 1
    As another answer has noted, there is the {% link ... %} tag which is recommended to be used, as it helps ensure links are made correctly, and it will give you an error if a link is broken. See jekyllrb.com/docs/liquid/tags/#link
    – Simon East
    Jan 12, 2021 at 7:04
25

If the internal content is on the same page then it is possible to link to it using the auto_ids feature. You enable this in _config.yml:

kramdown:
    auto_ids: true

With this enabled each heading gets an id ref based on the heading text. For example

### My Funky Heading

will become

<h3 id="my-funky-heading">My Funky Heading</h3>

You can link to this from within the same document by doing something like this:

The funky text is [described below](#my-funky-heading)

You can assign an explicit id if you prefer:

### My Funky Heading
{: #funky }

and link to it

The funky text is [described below](#funky)
3
  • That works even if you want to reference other elements than titles. Sep 20, 2019 at 12:26
  • This can also be extended for links in other pages. e.g.: [text] (/path/to/file/#funky)
    – Robur_131
    May 20, 2020 at 6:59
  • Note that the kramdown auto_ids feature is true by default so you have it enabled as long as you don't explicitly disable it _config.yml.
    – mefryar
    Aug 11, 2021 at 23:45
9

There are multiple ways of linking in Jekyll, some of which are now outdated.

With link tags

The recommended way to link to internal files is

[Link]({{ site.baseurl }}{% link path/to/file.md %})

Note that this will cause an error if the file moves or gets deleted.

With permalinks

To link to a page without causing errors (broken links instead):

[Link]({{ '/path/to/page/' | relative_url }})

Note that here you need to know the permalink of the page and pass it through the relative_url filter to ensure that it is prefixed with the base url of the site.

The permalink of a page depends on the permalink setting in your config file and the permalink key in the front matter of the file.

With jekyll-relative-links

If you want to use relative paths (and want the links to work in GitHub's markdown view), you should use jekyll-relative-links. This lets you write links like:

[Link](./path/to/file.md)

[Link to file in parent folder](../file.md)
2

Imagine this is your project directory:

project directory

To link "index.md" to a file inside folder "blog" called "20190920-post1.md", do the following:

  1. Open the file "index.md".
  2. Add the following:

    [any text](./relative path)

For example:

- [Sept 20th 2019 - Kikucare's Journey](./blog/20190920-post1.md)

Output:

enter image description here

1
0

Working in Jekyll 3.9.x:

In HTML: <a href="{{ '/blog/' | relative_url }}">Link to blog</a>

0

Sep 2023

Since Jekyll doesn't know which post you want to include, you need to include the full file name. You do not need to include the extension.

Date alert
Notice that the filename and the date category that output inside the <p> tag are different. That is because the post has a different date in the Front Matter. When the page renders to HTML, it looks at the Front Matter date.

{% post_url 2023-09-28-test-page %}

<!-- outputs this -->
<p>/2023/01/02/test-page.html</p>

To display a proper URL

You need to wrap the Liquid with brackets ( and ) and use [ ] to include your anchor text.

[A Test Page]({% post_url 2023-09-28-test-page %})

<!-- outputs this -->
<p><a href="/2023/01/02/test-page.html">A Test Page</a></p>

Rename a file after linking

If you rename your post file after linking, Jekyll will throw an error.

Error: Could not find post "2023-09-28-test-page" in tag 'post_url'. 
Make sure the post exists and the name is correct.
Error: Run jekyll build --trace for more information.

Include an attribute

You can use curly brackets to include your attributes. Notice the colon at the beginning.

[A Test Page]({% post_url 2023-09-28-test-page %}){:target="_blank"}

<!-- outputs this -->
<p><a href="/2023/01/02/test-23-page.html" target="_blank">A Test Page</a></p>

Include multiple attributes

To include more attributes, you can add them like regular HTML attributes followed by a space.

[A Test Page]({% post_url 2023-09-28-test-page %}){:target="_blank" class="active"}

<!-- outputs this -->
<p><a href="/2023/01/02/test-23-page.html" target="_blank" class="active">A Test Page</a></p>

Not the answer you're looking for? Browse other questions tagged or ask your own question.