VSCode link validator: Is there a way to make it work how I'd expect?

support
1

I’ll try to keep this brief, because hopefully I’m just missing an otherwise obvious setting somewhere. (Though I’ll also try to put all the terms someone might search for)

I’m using VSCode (Visual Studio Code) to work on a Hugo site.

I have the Markdown > Validate: Enabled and the Markdown > Validate > File Links: Enabled settings on.

When I include a link like check the [Events](/events) page, I get a warning that the “File does not exist at path” from the (link.no-such-file) linter.

If I have an /events/index.md at the root of the repo, not under /content, it’s fine.
If it’s /events/_index.md the warning triggers.

So my 2 questions:

  • Can I get VSCode and the Markdown features to use /content as the root directory when validating file links?
  • Can I have it allow for either index.md or _index.md as valid children to tell the linter that the link would be navigable?

Thanks :slightly_smiling_face:

Additional Search Terms

markdownlint
link warning
no such file

2

Don’t know if what you ask is possible, but I use Hugo’s relref shortcode instead, which gives error for broken files. relref doesn’t validate fragments by default, but jmooring has a post somewhere about render hooks that IIRC validates fragments as well.

But I agree it would be nice if the editor would validate these links (at least for the trivial usecases).

Update: Link to the post Link and image render hooks - Veriphor

3

heres a topic that has some background on that.

4

Hugo is a generator and not all files you have in your content folder will end up at the same file structure. This depends on the project setup and templates, render hooks, theme, static files …

A static validation on your markdown files may work for the simple cases, but not all the time. That’s why the linked topic and article use build time resolution which implicitly validates the markdown links.

whatever you do with static validation in VSCode does not ensure your link works after generating the real site.

All that said, here my thoughts on possible workarounds…

workaround for your first bullet:

place your markdown files in prj_root/events as you said that should work in VSCode

mount the events to the content folder

[module]
  [[module.mounts]]
    source = 'content'
    target = 'content'
  [[module.mounts]]
    source = 'events'
    target = 'content/events'

that way your VScode will see the events folder in root and Hugo will fetch them up from content/events

_index.md and index.md

in a standard site, both are rendered to events/index.html and the usual way for hugo to link would be /events/ → no warning with the linter, but no ctrl+click to open :-(. I don’t know a way around that one.

You can install the markdownlint extension which can be enhanced with plugins and custom rules. Check the docs, there’s a reference to the plugins

  • there’s an extension for “relative links” which has an option to configure a root folder. may work for your first point.
  • you can create custom filters for the underlying markdownlink-cli guess one could write one for the index problem.