Fixing incompatibility between markdown-link-check and not having every page managed as an Hugo section

[gwarf]

Currently all the markdown pages are created like this:

• having a folder for the page name, like about or concepts
• having the page content in _index.md files under those folder.

$ tree content/en/about
content/en/about
├── _index.md
└── concepts
    └── _index.md

This is in fact expected to be only done for sections and leads to having all the pages with a section-specific formatting.

Ideally pages under a section should not be added in a folder:

$ tree content/en/about
content/en/about
├── _index.md
└── concepts.md

The problem is that markdown-link-check is failing at finding the proper leaf file (like concepts.md).

We could try to address this problem in https://github.com/tcort/markdown-link-check or look for an alternative way to check files.
https://github.com/stevenvachon/broken-link-checker or https://github.com/celinekurpershoek/link-checker could be used to check the output rendered by Hugo, but error messages wouldn't allow to trace back to the source files.

[thebe14]

The problem comes from how Hugo renders markdown content to HTML. If you have the following source structure:

$ content/en/about
├── _index.md
└── concepts.md
└── section.png
└── concepts
        └── page.png

it will be rendered to this HTML structure when the site is deployed:

$ public/en/about
├── _index.html
└── section.png
└── concepts
        ├── _index.html
        └── page.png

This is why you can reference an image from a page markdown directly if the page's resources are in a folder named the same as the basename of the page, which is on the same level as the page. E.g. this ...[section image](section.png)... works in file _index.md, and this ...[page image](page.png)... works in file concepts.md, with the structure above. However, this only works AFTER the site was built by Hugo.

Markdown requires the paths to referenced resources to be relative to the file in which they are written, which is not true on our source tree above. And the only markdown linter we have checks links according to Markdown rules, then correctly fails the source as being incorrect.

[thebe14]

The solutions I see possible:

• we need another Hugo-aware linter (or we patch the one we are using)
• we check for links after the site is built (in which case we need a HTML link checker)

[gwarf]

Solution 1 is preferable as the error will link to the proper line in the source code, while for solution 2 it will likely not be the case.
We could try to report the issue to the upstream and see what they say.
Patching it for our repo only may be complex as it comes from a GitHub actions that is wrapping another tool.