404 links in documentation when viewed with mdbook

[4ydan]

Steps to Reproduce the Problem

cargo install mdbook mdbook-mermaid
cargo install --git https://github.com/ElektraInitiative/mdbook-generate-summary mdbook-generate-summary
mdbook serve --open

• Navigate to http://localhost:3000/architecture/12glossary.html
• scroll down
• press on any of the two hyperlink "here"

Expected Result

Navigate to the proper markdown

Actual Result

System Information

• PermaplanT: master
• Operating System: Inside a Rust Devcontainer in VSCode under Windows10
• Browser: Opera

And

Basically all of these need to be fixed

Weird to make it work offline in markdown and as mdbook, maybe replacing /doc/ with ../ might do the fix for most of these.

[markus2330]

Thank you, great findings! I can reproduce that these links are dead. backend was moved (now in doc/backend), the database/hierarchy.md seems to be some limitation of mdbook (seems like mdbook doesn't support absolute links).

Let us try out the link checker mdbook provides, maybe it would avoid such problems in future once we have it as part of CI.

[4ydan]

What do we think about a pre-commit hook solution to checking if the links work? Or is it maybe to inconsistent?

[markus2330]

If the mdbook link-checker solution is not working easily, it could be much better than nothing, depending on how similar the checks to what mdbook allows are (e.g. absolute links should be prohibited, as they don't work with mdbook afaik).

Imho broken links that lead to existing files not included in mdbook are not terribly problematic, people can open the file via some other way. (Of course the non-plus-ultra variant is if these links go to the repo, like implemented in libelektra.)