Homogenize link style

[dchiquito]

Fixes #342

I could not find the fail2ban demo video file, so that is the only remaining dead link.

The only change I'm not confident in is https://github.com/libp2p/docs/pull/343/files#diff-0cc46df6727c5d994526392f63afa1cb76f0eec3bd2d811c83c05044a0c4bee7L189 . I couldn't find any references to "content routing", so I changed the reference to discovery routing instead.

[dchiquito]

@p-shahi I converted all internal links to be of the form [foo]({{< ref "/concepts/bar.md" >}}). This means Hugo will fail to build if any links don't resolve. Sadly, it is much more verbose than a straightforward [foo](/concepts/bar). I could not find a way to get a link checker to work with internal links, so I think relying on Hugo is the best that can be done. Future writers would need to remember to adopt the more verbose link form wherever possible.

If that's not an acceptable solution, then I can do a find/replace to convert everything back to the simplest possible form. The links will be correct and the link checker will still verify external links, but there will be no CI test for internal links.

For whatever reason, neither Hugo nor any link checkers I found check heading IDs (concepts/foo#bar), so those are unverified and cannot be tested automatically AFAICT :(

[p-shahi]

@p-shahi I converted all internal links to be of the form [foo]({{< ref "/concepts/bar.md" >}}). This means Hugo will fail to build if any links don't resolve. Sadly, it is much more verbose than a straightforward [foo](/concepts/bar). I could not find a way to get a link checker to work with internal links, so I think relying on Hugo is the best that can be done. Future writers would need to remember to adopt the more verbose link form wherever possible.

If that's not an acceptable solution, then I can do a find/replace to convert everything back to the simplest possible form. The links will be correct and the link checker will still verify external links, but there will be no CI test for internal links.

For whatever reason, neither Hugo nor any link checkers I found check heading IDs (concepts/foo#bar), so those are unverified and cannot be tested automatically AFAICT :(

Thanks for the hard work @dchiquito
Having this checker in CI is great, but I agree with you that sadly it is more verbose and strays from normal markdown syntax.
I'd like to get @ElPaisano (IPFS docs maintainer) to weigh in here - wdyt?
Personally even with the added verbosity, I think this is worth it at the end of the day.

Also, I haven't looked into alternatives to lycheeverse myself, were there other alternatives you explored @dchiquito ?

[dchiquito]

I looked at https://github.com/JustinBeckwith/linkinator and https://github.com/wjdp/htmltest, but lychee seemed to be the best fit and the best supported tool.

[johnnymatthews]

Hi @dchiquito, thanks for this PR! From the looks of things, you're updating the link-checker in this repo. That might be unnecessary.

This repo is built using Hugo, which has a built-in internal link checker. By using {{< relref "/link/to/somewhere " >}} we can catch broken internal links before the site is built. We don't have to implement a link-checker CI/DI process for this.

Regarding external links: @ElPaisano has been working on a comprehensive CI/CD process for checking external links (and some other things like spell checking, and formatting). This process will likely be merged into this repo at some point soon.

I recommend that we:

• Remove the changes to .github/workflows/link-check.yml.
• Update all internal links to use the relref Hugo syntax

[ElPaisano]

Hi @dchiquito, thanks for this PR! From the looks of things, you're updating the link-checker in this repo. That might be unnecessary.

This repo is built using Hugo, which has a built-in internal link checker. By using {{< relref "/link/to/somewhere " >}} we can catch broken internal links before the site is built. We don't have to implement a link-checker CI/DI process for this.

Regarding external links: @ElPaisano has been working on a comprehensive CI/CD process for checking external links (and some other things like spell checking, and formatting). This process will likely be merged into this repo at some point soon.

I recommend that we:

• Remove the changes to .github/workflows/link-check.yml.
• Update all internal links to use the relref Hugo syntax

@dchiquito @p-shahi I agree with Johnny's take here that we don't need to add this GH action. We can implement filecoin-project/filecoin-docs#2086 in this repo, which adds an external link check, markdown format chek, spell check and writing style check as a precommit step. Precommits can also be triggered as a GH action, so we can lint pre and post commit (if thats what the team wants)

@dchiquito thanks for updating the links! That's super useful

[ElPaisano]

... although, looking into lycheeverse more, it might be worth using this in filecoin-project/filecoin-docs#2086, instead of https://github.com/tcort/markdown-link-check, which is what is currently used. It looks like a good tool. However, because this is a rust based tool, it won't play nice with NPM, like markdown-link-check. So that would require further refactoring

[p-shahi]

@ElPaisano will you also be porting over the work in filecoin-project/filecoin-docs#2086 to this repo?
If that's the case then I think we can close this PR

sorry for not knowing this was happening earlier @dchiquito otherwise I would have definitely let you know.

[dchiquito]

@p-shahi Most of the work in this PR is finding and adjusting relative links to use Hugo's ref function. It seems like the consensus is that is a worthwhile change (or using relref, but that's a simple find/replace), so the CI changes can simply be removed and the rest of the PR merged.

[p-shahi]

That sgtm @dchiquito , we can add the filecoin-project/filecoin-docs#2086 changes later

[p-shahi]

lgtm