Add support for relative links (../content/page) to broken link checker

[onnimonni]

Feature Request

Environment

Zola version: zola 0.17.2

Expected Behavior

I was using expecting link checker to check broken relative links or external links but it doesn't.

Current Behavior

When I add relative links with the special @ syntax I can get errors when the content doesn't exist.

So for example when adding following markdown it fails properly:

[Broken link failing](@/docs/contributing/not-existing.md)

And outputs the error

Error: Failed to build the site
Error: Failed to render content of /Users/onni/Projects/adidoks-test/content/docs/getting-started/introduction.md
Error: Reason: Broken relative link `@/docs/contributing/not-existing.md` in docs/getting-started/introduction.md

But it doesn't seem to check relative links which are done like this:

[Broken link not failing](../contributing/not-existing)

This kind of relative links are preferred for example in the Adidoks theme example content

Am I just using it wrong?

Step to reproduce

Create content into your page and add following relative link and they should both produce build errors but don't at the moment:

[Broken link not failing](../contributing/not-existing)

EDIT: Removed the external links checking since those were working just fine but I just didn't know about $ zola check command.

[Keats]

We are checking external links in zola check. We are not checking relative links in any way though

[onnimonni]

Thanks! I tried to find this information and I will create a PR about mentioning the $ zola check command in the configuration documentation.

So probably then only the relative links aspect of this ticket should stay open. Do you want me to edit this?

[Keats]

So probably then only the relative links aspect of this ticket should stay open. Do you want me to edit this?

Yes please, it's a feature request not a bug report. I'm not sure how to handle relative links when you can have page aliases

[onnimonni]

I edited this and it's now feature request.

I think when parsing the markdown you know the current pages url and you could just convert these into the same format that you already do know how to parse.

Let's say that I'm on a page: @/docs/contributing/guide.md and it contains relative url ../not-existing you could then just 1. Take the directory part of the @/docs/contributing/guide.md -> @/docs/contributing/ 2. add the relative link to the directory -> @/docs/contributing/ + ../not-existing -> @/docs/contributing/../not-existing 3. It seems that it's pretty easy to canonicalize the urls using std::fs::canonicalize (See more from here: https://stackoverflow.com/a/38384901) 4. Then the canonicalized version of the string you do already know how to link check: @/docs/contributing/../not-existing -> @/docs/not-existing?

Which kind of case did you have in mind with the page aliases?

[Keats]

How do you actually write relative links if we expect the relative links to point to markdown files? That's the whole point of starting with @: to know when we are targeting markdown content rather than an actual link.

[onnimonni]

Let me show you how I got here:

1. As a new user of Zola I visit getzola.org and then navigate to the themes section.

2. I see a the 2nd top most theme there is Adidoks:

3. I navigate to their Github page and start trying the theme out.

4. I see that this theme is heavily using the ../ kind of relative links and they seem to work just fine: https://github.com/aaranxu/adidoks/blob/main/content/docs/contributing/how-to-contribute.md?plain=1

5. I'm expecting these links to be automatically checked after reading about them in the Zola documentation about internal links

You can see multiple examples of how they are using the relative ../ links there 👍

[onnimonni]

But again I see that my expectations were clearly wrong here. I can help to improve the links checking documentation that it does not currently support relative links so using the @ syntax is mandatory to get this feature.

[Keats]

This file is pointing to the URL, not the markdown file. They happen to have the same slug but that's not required. Now imagine your page in https://github.com/aaranxu/adidoks/blob/main/content/docs/contributing/how-to-contribute.md?plain=1 is also rendered at another URL as an alias, eg /contributing. The relative path will be correct for the current page (/docs/contributing/how-to-contribute/ but wrong for the alias since there won't be a page at ../code-of-conduct. will not exist.

[onnimonni]

I understand but the these will still cause a broken link which definitely can be seen in the end result.

As an engineer I would guess that this can be solved by building a tree of internal pages and checking if the relative link will actually go to anything meaningful.

This would greatly enhance the experience of both writer and reader of a Zola site 💪

[tv42]

It seems the produced output page can have an alias, but the source markdown is at a single known path.

My expectation is that I can write links from source content A to source content B and if the produced output for source content B is at some special location, well then the produced output link should point to that.