jekyll markdown internal links

Question

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

[[link]] 

Solution 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

Solution 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.

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

Solution 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)

Solution 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)

View more solutions

Comments

[Kadarach]

Any idea how to internally link to a page?

[northben]

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

[Ciro Santilli OurBigBook.com]

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.

[alexsalo]

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

[teardrop]

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

[Amanda]

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

[David Douglas]

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

[Antônio Medeiros]

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

[oleksa]

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

[Robur_131]

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

[Henry Schreiner]

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.

[Simon East]

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

[mefryar]

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.