A Jekyll plugin to convert relative links to Markdown files to their rendered equivalents.
Let's say you have a link like this in a Markdown file:
[foo](bar.md)
While that would render as a valid link on GitHub.com, it would not be a valid link on Pages. Instead, this plugin converts that link to:
[foo](bar.html)
It even work with pages with custom permalinks. If you have bar.md
with the following:
---
permalink: /bar/
---
# bar
Then [foo](bar.md)
will render as [foo](/bar/)
.
The default Jekyll's configuration permalink: pretty
in the _config.yaml
file removes the .html
extensions from the generated links.
Because Markdown files rendered by GitHub Pages should behave similar to Markdown files rendered on GitHub.com
gem 'jekyll-relative-links'
plugins:
- jekyll-relative-links
Note: If you are using a Jekyll version less than 3.5.0, use the gems
key instead of plugins
.
You can configure this plugin in _config.yml
under the relative_links
key. This is optional and defaults to:
relative_links:
enabled: true
collections: false
To exclude specific directories and/or files:
relative_links:
exclude:
- directory
- file.md
Setting the collections
option to true
enables relative links from collection items (including posts).
Assuming this structure
├── _my_collection
│ ├── some_doc.md
│ └── some_subdir
│ └── another_doc.md
├── _config.yml
└── index.md
the following will work:
File | Link |
---|---|
index.md |
[Some Doc](_my_collection/some_doc.md) |
index.md |
[Another Doc](_my_collection/some_subdir/another_doc.md) |
_my_collection/some_doc.md |
[Index](../index.md) |
_my_collection/some_doc.md |
[Another Doc](some_subdir/another_doc.md) |
_my_collection/some_subdir/another_doc.md |
[Index](../../index.md) |
_my_collection/some_subdir/another_doc.md |
[Some Doc](../some_doc.md) |
rellinks
filterIn addition to automatically converting relative links in your Markdown files, this plugin also provides a Liquid filter called rellinks
that can be used to convert relative links in content that has already been processed by Jekyll's markdownify
filter.
This is especially useful when you have Markdown content in your front matter that you want to display with properly converted links.
For example, if you have a page with a sidebar defined in the front matter:
---
title: My Page
sidebar: |
My page's sidebar **content**.
Might have [a link somewhere](./other.md)
---
You can use the rellinks
filter in your template like this:
<aside class="sidebar">
{{ page.sidebar | markdownify | rellinks }}
</aside>
The rellinks
filter will transform any relative links to Markdown files in the HTML output from the markdownify
filter, converting them to their rendered equivalents.
Even if the plugin is enabled (e.g., via the :jekyll_plugins
group in your Gemfile) you can disable it by setting the enabled
key to false
.