Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/benbalter/jekyll-relative-links
A Jekyll plugin to convert relative links to markdown files to their rendered equivalents
https://github.com/benbalter/jekyll-relative-links
github-pages jekyll jekyll-plugin redirects
Last synced: 5 days ago
JSON representation
A Jekyll plugin to convert relative links to markdown files to their rendered equivalents
- Host: GitHub
- URL: https://github.com/benbalter/jekyll-relative-links
- Owner: benbalter
- License: mit
- Created: 2016-11-17T05:38:00.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2024-06-11T14:26:13.000Z (7 months ago)
- Last Synced: 2025-01-10T00:10:02.756Z (12 days ago)
- Topics: github-pages, jekyll, jekyll-plugin, redirects
- Language: Ruby
- Homepage:
- Size: 203 KB
- Stars: 141
- Watchers: 7
- Forks: 37
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE.md
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
# Jekyll Relative Links
[](https://github.com/benbalter/jekyll-relative-links/actions/workflows/ci.yml)
A Jekyll plugin to convert relative links to Markdown files to their rendered equivalents.
## What it does
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.
## Why
Because Markdown files rendered by GitHub Pages should behave similar to Markdown files rendered on GitHub.com
## Usage
1. Add the following to your site's Gemfile:
```ruby
gem 'jekyll-relative-links'
```
2. Add the following to your site's config file:
```yml
plugins:
- jekyll-relative-links
```
Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`.
## Configuration
You can configure this plugin in `_config.yml` under the `relative_links` key. This is optional and defaults to:
```yml
relative_links:
enabled: true
collections: false
```
### Excluding files
To exclude specific directories and/or files:
```yml
relative_links:
exclude:
- directory
- file.md
```
### Processing Collections
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)`
### Disabling
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`.