How to create link to an MD page in same subdirectory (newbie)

Help
1

Hi,

I’ve successfully migrated my blog over to Jekyll 4. Linking between blog posts is super easy, but I’m stuck while trying to link from one page to another, in the same subdirectory.

Example:
electronics/rfid/index.md
electronics/rfid/proxmark3.md

The “electronics” subdirectory is immediately under my Git repo root, so not under _pages or _posts. I have ‘electronics’ in my Front Matter defaults in _config.yml (defaults > scope > path)

I want to create a link to the proxmark3 page from the index page. I searched the forum and found How to link from .md page to other page but those solutions seem to assume that the pages are in the toplevel?

Code example, electronics/rfid/index.md:

Here is my link to [Proxmark3]({% link proxmark3.md %})

This fails because Jekyll cannot find the “proxmark3.md” file even though it is really there :wink:

ed@BigMac% bundle exec jekyll build --trace
[ ... ]
Incremental build: disabled. Enable with --incremental
      Generating... 
       Jekyll Feed: Generating feed for posts
  Liquid Exception: Could not find document 'proxmark3.md' in tag 'link'. Make sure the document exists and the path is correct. in electronics/rfid/index.md
bundler: failed to load command: jekyll (/usr/local/lib/ruby/gems/3.1.0/bin/jekyll)
/usr/local/lib/ruby/gems/3.1.0/gems/jekyll-4.2.2/lib/jekyll/tags/link.rb:32:in `render': Could not find document 'proxmark3.md' in tag 'link'. (ArgumentError)

Make sure the document exists and the path is correct.

The proxmark3.md file renders normally when I remove the link from index.md that causes the build to fail, so the file is there and Jekyll seems to understand it.

I’ve tried all kinds of variations, for example:

Here is my link to [Proxmark3]({% link proxmark3.md %})
Here is my link to [Proxmark3]({{ page.dir }} {% link proxmark3.md %})

For “posts” this all works perfectly, but for “pages” I’m not getting anywhere. I must be doing something wrong, but I cannot seem to figure out what that is.

Any help would be appreciated :wink:

Regards,
Ed.

2

I believe you need to include the path the page. Something like (untested code):

{% link /electronics/rfid/proxmark3.md %}

Docs at: https://jekyllrb.com/docs/liquid/tags/#links

3

Hi @chuckhoupt,

Thanks for your suggestion - I tried that, but I still cannot get it to work ;-(

When I use a link like this:

[Proxmark3]({% link /electronics/rfid/proxmark3.md %})

I get a build-time error:

  Liquid Exception: Could not find document '/electronics/rfid/proxmark3.md' in tag 'link'. Make sure the document exists and the path is correct. in electronics/rfid/index.md
             Error: Could not find document '/electronics/rfid/proxmark3.md' in tag 'link'. Make sure the document exists and the path is correct.

I then changed that link, removing the leading slash. This looks better: the build works, the local “Jekyll serve” site also works, but the “Live” site returns a 404 due to a bad link:

* Getting started with a cheap [Proxmark3]({% link electronics/rfid/proxmark3.md %}) from AliExpress

The generated HTML link is:

  <li>Getting started with a cheap <a href="/electronics/rfid/proxmark3">Proxmark3</a> from AliExpress</li>

The generated link is just “proxmark3” instead of “proxmark3.html” as I would expect.

I think that linking between webpages is basic functionality, so I feel I’m overlooking something simple in Jekyll here :wink:

Do I really need to keep pages under “_pages”, like blog posts are under “_posts”? Perhaps there’s some Jekyll magic that I’m missing?

Thanks!
Ed.

4

Hi, my initial reply contained an example of the generated HTML, so it is being held up by Akismet - hoping that it will re-appear shortly :wink:

5

For now, I have found a workaround (solution?): instead of linking to the Jekyll source file as one normally would, I need to link directly to the Jekyll-generated output file.

So, summarising: I expected one of these links to work, but they do not:

{% link proxmark3.md %}
{% link electronics/rfid/proxmark3.md %}

But this works:

{% link proxmark3.html %}
{% link /electronics/rfid/proxmark3.html %}

I did not expect to have to link to the Jekyll-generated output file. For “posts”, you link to the Jekyll source file (Markdown) and Jekyll takes care of the rest. I was assuming the same would work for “pages”.

Regards,
Ed.

6

In my testing, it seems that link is very sensitive to whether a file has YAML front-matter or not. Files without front-matter need to be references by their exact output name. Files with front-matter can be references by input name (e.g. test.md).

Is it possible that your Markdown files (like proxmark3.md) don’t have front-matter? For example, maybe you are using the jekyll-optional-front-matter plugin (which is activated by default on Github Pages)?

7

Hi,

I really don’t think Jekyll expects the link tag to be provided the generated URL. That defeats the purpose of having the tag altogether.

The link tag in fact expects one to provide the relative_path of the resource. The relative_path is the path relative to the site.source irrespective of where the link tag is used. Therefore, your electronics/rfid/index.md should link to its sibling proxmark3.md using the following construct:

{% link electronics/rfid/proxmark3.md %}

The only overhead is to make sure whether the resource is a Static File (doesn’t contain front matter) or otherwise. The relative_path of static_file objects must always have a forward slash at the beginning:

{% link /images/graphic.png %}

A

8

Thanks for the reply!

The Front Matter on the proxmark3.md page is:

---
permalink: /electronics/rfid/proxmark3
title: 'Proxmark3 Easy'
date: 'Thu  9 Feb 2023 13:40:29 CET'
layout: single
---

The Front Matter on the index.md page is:

---
permalink: /electronics/rfid/
title: 'RFID and NFC'
date: 'Thu  9 Feb 2023 13:40:29 CET'
layout: single
---

I’m wondering if the Front Matter on the proxmark3.md page is correct - it has no .html extension. But having to specify the extension also kind of defeats the purpose :wink:

9

Hi, I fully agree that having to specify the generated URL is a bit strange.

However, when I specify the link as:

* Experiment1: [Proxmark3](electronics/rfid/proxmark3.md)

The generated link results in a 404 error - and it has a duplicate path:

http :// localhost:4000/electronics/rfid/electronics/rfid/proxmark3.md

Specifying the link with an absolute path like this:

* Experiment2: [Proxmark3](/electronics/rfid/proxmark3.md)

The generated HTML now has the correct path, but is still broken as it refers to .md instead of .html:

http :// localhost:4000/electronics/rfid/proxmark3.md

So we both agree, but it seems Jekyll does not :slight_smile:

Regards,
Ed.

10

Unfortunately, I am not able to reproduce this issue using a bare bones site (scaffolded by running jekyll new ...) and manually creating the RFID pages using the front matter info provided above.
Can you push a public repository with just the minimal files needed to reproduce the issue (i.e., the two RFID pages, config file, Gemfile)? The pages’ contents have no relevance so the proxmark page in the sample repo could be just a few words as its “content” and the rfid index page with just the {% link ... %} tag(s) as used in the original site as its “content”. Let the front matter be as is in the original site.

11

Maybe a typo, but the experiment examples are not using the link tag – they are just plain Markdown inline links. Did you mean:

* Experiment1: [Proxmark3]({% link electronics/rfid/proxmark3.md %})
12

Thank you @chuckhoupt and @ashmaroli !

I was doing too many experiments simultaneously - and I forgot to re-add the “link” tag in the example I posted.

It turns out the issue was indeed related to incorrect Front Matter. If I specify the full permalink URL like this:

permalink: /electronics/rfid/proxmark3.html

The following link code now works:

* Link with relative URL: [Proxmark3]({% link electronics/rfid/proxmark3.md %})

It still feels a little surprising that a link without a path component does not work (I would have preferred this to work, because I would not have to maintain the path in several places:

* Link without path does not work [Proxmark3]({% link proxmark3.md %})

This results in a rendering error:

  Liquid Exception: Could not find document 'proxmark3.md' in tag 'link'. Make sure the document exists and the path is correct. in electronics/rfid/index.md

Again, thanks for helping me out! Kind regards,
Ed.

13

Another option is to remove the permalink field, since Jekyll will auto-create the same permalink based on the file’s path and base name.