[Feature] Disallow File Extension

[its-miroma]

Description

VitePress recommends using relative links without file extensions. For example:

[Correct](./file)
[Wrong](./file.md)

Describe the solution you'd like

Please add an option (off by default) so that the linter warns of links with extensions.

Describe alternatives you've considered

markdownlint-rule-search-replace with this configuration:

config:
  search-replace:
    - name: no-file-extension-in-links
    message: "Don't add the file extension to links"
    searchPattern: "/\\[(.*?)\\]\\((.*?)\\.md((?:#[a-z0-9-]+)?)\\)/g"
    replace: "[$1]($2$3)"
    searchScope: text
customRules:
  - ./node_modules/markdownlint-rule-search-replace/rule.js

[theoludwig]

Hey! Thank you for taking the time to suggest a new feature idea. @its-miroma

That's an interesting use case, does that mean we should try to guess the extension only for a list of "well known" extensions, making work only for .md and .html. What happens if there is a link [Link](./abc), and a file abc.pdf for example, is that still considered valid?

What happens if there are multiple files named abc (but with different extensions), should that mean we need to iterate through all files with the filename used in the link, and check if there is at least one with .md or .html extension? What if there is a file abc (without file extension), is that considered valid?

It seems like adding this feature adds quite a bit of complexity, that is not necessarily worth it.

the best practice is to omit file extensions so that VitePress can generate the final URLs based on your config.

So what happens if you use relative links with file extensions, with Vitepress? I'm not sure I understand from the docs, it seems like more a recommendation/best practice than having a real impact on the end result? It can't generate final URLs, if links includes file extensions?

[its-miroma]

It seems like adding this feature adds quite a bit of complexity

I understand.

I have updated the alternatives you've considered section with a markdownlint-rule-search-replace rule that I'm currently using. I think the workaround is good enough for my use case, feel free to close this issue.

---

Does that mean we should try to guess the extension only for a list of "well known" extensions?

What happens if there is a link [Link](./abc), and a file abc.pdf for example, is that still considered valid?

What happens if there are multiple files named abc (but with different extensions)

What if there is a file abc (without file extension), is that considered valid?

No, links without the extension only apply for Markdown files (.md)

[!IMPORTANT] This only applies to VitePress, other engines such as VS Code work differently.

The feature request asks for an option, off by default, for this.

You may want to implement additional configuration for a list of extensions that this applies to.

---

So what happens if you use relative links with file extensions, with Vitepress?

VitePress has some features for transforming the URLs so that it removes/changes the extension shown in the browser's address bar. For example, cleanUrls allows VitePress to remove the file extension.

If the link has the extension, will cause the browser to briefly load the URL with the extension, to then change it. For example, if a link goes to ./file.md, the browser will briefly show ./file.md and then show ./file.

Without the extension, the URLs are processed before they are shown in the browser, so the brief flash does not appear.

It can't generate final URLs, if links includes file extensions?

It can, it's just a cosmetic issue.

[theoludwig]

Yeah markdownlint-rule-search-replace is a good workaround to at least enforce that there are no links with the .md extension, but it doesn't check if the file exists.

The feature request asks for an option, off by default, for this.

You may want to implement additional configuration for a list of extensions that this applies to.

Yes, default behavior, should definitely stay as is, but why not add a new option + config for list of file extensions to enable this feature. I'm not against someone implementing this feature, and opening a PR, it might make this rule usable in more scenarios.