Resolve "/slug" to "/slug/index.md" or "/slug.md"

[tillprochaska]

Hi there, I’m trying to use lychee to check links in the Markdown source of a documentation website. We use a static site generator that builds HTML pages based on that:

docs/getting-started/index.md => docs/gettings-started/index.html
docs/getting-started/installation.md => docs/getting-started/installation.html

Links to other documentation pages look like this:

[Getting Started](/docs/getting-started)
[Installation](/docs/getting-started/installation)

Lychee fill detect the links in the example above as broken (even though they are actually working in the generated site).

I think this behavior is actually quite common for many SSG/documentation tools, but it may be out of scope for Lychee to support this. But maybe there’s a more generic configuration option I’m missing that could be used to support this use case?

A workaround I have considered is running lychee with the generated HTML output rather than the Markdown source, but I’d prefer not to do that if possible.

[tillprochaska]

Another workaround that would work well in our case is to link to the actual Markdown files in the source and post-process the links in our build step -- we have to do some link transformations anyways. This works out of the box with lychee…

[Getting Started](/docs/getting-started/index.md)
[Installation](/docs/getting-started/installation.md)

[mre]

Oh, that was quick. Glad you found a workaround!

I was about to point out that we got an --offline flag, which disables checks which require network access.

Coming back to the actual problem, another way would be to use remap I guess:

lychee --remap '/docs/(.*) /docs/${1}.md'

We don't support capture groups yet, but we could add that if it helps. This would remap (rewrite) /docs/getting-started to /docs/getting-started.md. Not sure how well this would scale for your use-case, though. In general I'm a big fan of making such things explicit like you did.

[tillprochaska]

Hey @mre, thanks for your response! Yes, I had a look at remap, but I think the problem is that /docs/installation could map to /docs/installation.md or /docs/installation/index.md -- not sure if it would handle that?

Anyways, I think I actually prefer the workaround/explicit solution. It also ensures that I can follow links when browsing raw Markdown files e.g. in the GitHub web UI.

[mre]

Yup, explicit is better; I agree.

The issue you describe can't be resolved by using remap alone. For that, lychee would have to know more about how static site generators work and even which static site generator is in use because they differ in functionality. If the two options (/docs/installation.md and /docs/installation/index.md) both can occur in the same codebase then it gets really tricky.

But glad you found a workaround, so there isn't much else we have to do here. 👍