jekyll markdown internal links

Question

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

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.

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

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)

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)

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: