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.

[hoijui]

I am representing a huge community here (people documenting machine plans with markdown).

each machine has a git repo, and part of it is documentation in markdown. this are multiple files in different directories, linking to each other with relative links. These links work in the source, in IDEs: We can click on them and browse the Markdown file just as we would the HTML in the browser. They can also be checked locally by link checkers. This scenario should allow us to generate eBooks, PDFs and static HTML sites. I would except any static site generator to support dumping any machines repo (containing the markdown files) into the content/ folder, and then generate static HTML pages with the same directory structure like the input, and the links being converted from *.md to *.html. In my mind, this should be the default behavior of any site generator. This would make them interchangeable = non-lock-in, and it would be very obvious for the user what is happening. Everything else that reduces portability, should be opt-in extras.

Does something like this exist? Am I looking in the wrong places?

[Keats]

I would except any static site generator to support dumping any machines repo (containing the markdown files) into the content/ folder, and then generate static HTML pages with the same directory structure like the input, and the links being converted from .md to .html. In my mind, this should be the default behavior of any site generator. This would make them interchangeable = non-lock-in, and it would be very obvious for the user what is happening.

Well that's kinda what happens, unless you use some features like having the date in the filename, or changing the path manually in the front-matter, or use aliases. I'd rather avoid touching normal (eg not starting with @) links when processing things.

[hoijui]

the links starting with @ are zola specific, so that means lock-in in my understanding.

when converting bunch of MD files - that contain links to each other - to HTML, how likely is it -or in what scenarios does it occur - that one wants the relative links within HTML to still point to the MD files? I am sure you have seen much more of what it out there and have good reasons, and after-all, it seems to be common to not touch these links, but to me it is really weird.