Add remark-validate-relative-links plugin

[webpro]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and discussions and couldn’t find anything or linked relevant results below
• I made sure the docs are up to date
• I included tests (or that’s not needed)

Description of changes

Part of

• https://github.com/webpro/remark-preset-webpro
• https://github.com/webpro/mdxlint-preset-webpro

Has already been quite useful in two projects:

• release-it/release-it@6e6dd4b
• webpro-nl/knip@a8d0bfd

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (f1f9321) to head (654a107).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1474   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            6         6           
  Lines          138       138           
=========================================
  Hits           138       138           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ChristianMurphy]

I'm not sure I understand this plugin from the readme, it looks like it does the same thing as https://github.com/remarkjs/remark-validate-links ?

ALso this doesn't appear to have types? Or be published to npm? Or have a CI/CD job testing it. All are things we look for in something to recommend to the community

[webpro]

Good points!

So, I started out by using remark-validate-links. But wanted to include/validate only relative links. With "skipPathPatterns": ["^/"] I noticed it resolves everything to absolute paths so the result is that all links are excluded (there isn't really a way around this, right?). Also was looking for something simpler without the "did you mean.." output (auto-completion in the editor is enough for me). So it's very similar indeed but the difference is that it validates only relative links. No frills.

The plugin is published at https://www.npmjs.com/package/remark-validate-relative-links. There's some basic types, the plugin does not take options (yet?).

I'll add some tests right away.

[remcohaszing]

I have some tips.

• You can type check JSDoc types with tsc and publish type definitions. I strongly recommend doing so. This also means that dependencies of those emitted types should go in package.json

• @types/vfile is outdated. You should depend on vfile instead.

• The following jsdoc:

  /**
   * @typedef {import('mdast').Root} Root
   */

  is equivalent to the following TypeScript:

  export type Root = import('mdast').Root

  This defines a new type named Root. This type is equivalent to (but not the same as) the Root type exported by mdast. This Root type is then exported.

  Most of the times you should do this:

  /**
   * @import { Root } from 'mdast'
   */

  This is equivalent to:

  import type { Root } from 'mdast'

  This only imports the Root type from mdast locally.

  If you intend to re-export a type, you can write the following in TypeScript:

  export type { Root } from 'mdast'

  Unfortunately there’s not jsdoc equivalent.

• Relative links don’t have to start with a dot. The following are practically equivalent:

  [example](example.md)
  [example](./example.md)

  I think relative paths can’t start with a protocol, slash, or hashtag.

• You can use mdast-util-to-string to get the text content of an mdast node.

• I believe there are some smarter slugger implementation available. Notably they may deal with slugs of duplicate headings.

[webpro]

Thanks a bunch for the tips, much appreciated. Applied most of it and released v1.

[wooorm]

I think relative paths can’t start with a protocol, slash, or hashtag.

// is relative to the current protocol, also ? starts query parameters.
But then ? and # are relative to the current path. And /asd is relative to the repo. And the // is relative to the protocol. So “relative” is a very vague term.
Not the exact same but maybe useful are https://github.com/micromark/micromark/blob/774a70c6bae6dd94486d3385dbd9a0f14550b709/packages/micromark-util-sanitize-uri/dev/index.js#L27 and https://github.com/micromark/micromark/blob/774a70c6bae6dd94486d3385dbd9a0f14550b709/test/io/misc/dangerous-protocols.js