jekyll markdown internal links
MarkdownJekyllMarkdown Problem Overview
Jekyll uses Markdown-formatted links, but how can I link to internal content?
[[link]]
Markdown Solutions
Solution 1 - Markdown
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.
Solution 2 - Markdown
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 - Markdown
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 - Markdown
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 - Markdown
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)