feat: create Astro integration wrapper for plugin

[techfg]

Currently, this library is Astro specific but it doesn't take a dependency on Astro in any way. Some of the logic is very Astro specific but in actuality there is very little of it. Without too much of a challenge, the plugin could be made generic to handle md/mdx links in general, rather than just Astro.

That said, it's not the stated mission of the plugin to transform links for anything but Astro. Along that line, I think it makes sense to create a pure Astro integration. This would allow for a few things:

1. Take dependency on Astro directly to leverage APIs, types, etc.
2. Ability to access Astro config information and utilize it instead of having to duplicate plugin options like basePath, etc.
3. Ability to leverage Astro APIs
4. Would take more R&D but possibly the ability to be much more robust with resolving URLs than can currently reliably support.

As an example, checkout starlight-links-validator. This plugin validates links contained within markdown. I haven't fully explored it and/or the possibilities of what a true integration could open doors for but there is likely something there to be explored/considered.

Look forward to hearing thoughts!

Edit: The above would come with the downside of having to decide on which versions of Astro to support and the additional maintenance cost of keeping up with Astro releases, backwards compat, etc. This requirement kind of already exists but it's rather loose since its just directory structures that are relied on from Astro and not APIs, types and/or any other internals. Short story, there are pros/cons but its possible being a full fledged integration would yield benefits and could be worth at least a POC to explore further.

[vernak2539]

This is actually a really interesting option. I've not looked into integrations much, so i'll have to have a look and get back to you on this. I'm a bit strapped for time these days, but let's see where we end up.

[alexrecuenco]

With Astro Starlight and my simple docs setup, the option contentPath: "src/content/docs" works (as far as I have tried)

So you would do something like

import type { Options as AstroRehypeOptions } from "astro-rehype-relative-markdown-links";

const linkOptions: AstroRehypeOptions = {
  contentPath: "src/content/docs",
};

export default defineConfig({
...
  markdown: {
    rehypePlugins: [[rehypeAstroRelativeMarkdownLinks, linkOptions]],
  },
 ...
)

PS: The types of Options doesn't show for me, no matter what I try, while I get the other types.

[techfg]

@alexrecuenco - Thanks for the info. Couple of questions:

1. Regarding your comment about how to configure contentPath, sorry, I'm not fully understanding if you are just trying to give of an example of how to use the plugin as its currently written or if this has something to do with making the plugin a full astro integreation or something else. Can you provide some context on that portion of your comment?
2. Regarding the types not showing, is this only when hovering over the type itself, is it when setting the properties of linkOptions that intellisense doesn't show them for you when typing? I know there is a problem when hovering (I have a solution for this) but want to make sure I'm not missing something else.

Thanks!

[alexrecuenco]

Yes. My apologies for confusing you all.

1. The issue mentions starlight, and this is the first search result when you look for integrating relative paths with starlight, I was just trying to contribute a somewhat working current example. I may have placed this comment in the wrong issue.
2. The options types dont show on hover. When I trigger auto-complete on a property name, it is also empty. It does know how to follow the type when you command-click on it, and takes you to the zod inferance… but the type is getting erased somewhere.

[techfg]

Thanks for the info @alexrecuenco, appreciate the follow-up!

1. Gotcha, makes sense, just wanted to make sure I wasn't missing anything that you were indicating was an issue - good to know you were just providing a working sample :)
2. The hover I'm aware of, the issue is that Options is defined as an interface vs. a type and typescript won't follow interfaces on hover (see https://github.com/microsoft/TypeScript/issues/38040) - I'm working on a fix for this as Options can be a type, it was just originally an interface and maintained that way throughout the changes earlier this year. Regarding "When I trigger auto-complete on a property name", can you provide more specifics on what you mean by this (e.g., how you are trigging auto complete) - possibly include a video so I can better understand what you mean?

Thanks!

[alexrecuenco]

Hm. I an not sure this is the issue to clutter with this.

But what I mean is

const o: Options = {
  |
}

Where | is the cursor.

It will not show property names if you trigger auto-complete, like it would do usually.

[techfg]

Agreed this isn't the issue for this, was planning on creating a new issue to track what you found but just want to make sure I'm understanding what you're seeing.

Sorry, but unfortunately I'm still not sure what you mean by "trigger auto-complete" - when I start typing a property name, intellisense detects and displays the corresponding properties in Options - possibly I'm misunderstanding what you mean by "auto-complete".

Would you mind creating a new issue with the two problems you have found including detailed steps on how to reproduce, specifically around how you "initiate" and what you mean by "auto-complete"? Once created, I'll review and work on a fix.

Thanks!