jekyll markdown internal links

Question

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

[[link]] 

Aronarondel

Answer 1

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

Griffe

Any idea how to internally link to a page? – Livvie

Looks like it is not possible to link to a page. This PR was closed without being merged: github.com/jekyll/jekyll/pull/369 – Angel

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. – Eisegesis

If you have subdirs: [Link's Text]({% post_url /dirname/2010-07-21-post %}) – Subito

Just a small note: do not include the extension in 2010-07-21-name-of-post. – Englebert

This worked fine for me [pivot]({% post_url 2015-02-03-pivot.md %}) -- using post_url as well as the file extension. – Oblate

Answer 2

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.

Inkhorn

I also found this documentation page helpful - jekyllrb.com/docs/liquid/tags/#link – Sanderson

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 %}) – Mortar

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. – Osteoclast

Answer 3

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 %}

Skittish

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 – Bowne

Answer 4

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)

Disseisin

That works even if you want to reference other elements than titles. – Scarper

This can also be extended for links in other pages. e.g.: [text] (/path/to/file/#funky) – Earnest

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. – Sticker

Answer 5

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)

Tomikotomkiel

Answer 6

Imagine this is your 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:

Kershaw

What if Jekyll then keeps the link to the .md file and does not convert .md to .html? -- Then the plugin github.com/benbalter/jekyll-relative-links should be activated. – Gibbon

Answer 7

Working in Jekyll 3.9.x:

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

Lorylose

Answer 8

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>

Muskeg