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 Intellisense should show internals of an interface declaration on hover microsoft/TypeScript#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!

[techfg]

@alexrecuenco - Thanks again for mentioning the hover & intellisense issues! I've finally been able to re-create both of them and created #72 to track.

[vernak2539]

@techfg thinking about this one out loud.

• Do you think providing this as an additional plugin, alongside the rehype plugin, would be the right path forward?
  • It would mean we'd abstract the base functionality into a shared location and use it both places I'd think
  • Or, actually, taking your example of https://github.com/HiDeoo/starlight-links-validator it looks like it would just be using the rehype plugin internally...
• We'd still have the problems with the version support, but hopefully we'd be able to get the astro version from the integration (I'll have to look more into this)
• I do like the idea that it would be directly integrated into astro... may allow for easier things, but also may not

It would definitely be interesting to give a shot to explore this more!

[vernak2539]

Hmm, so had a look at the integrations API, and it does seem like we'd not have access to the astro version / astro meta data. This would make it a bit more difficult to support all versions of astro "automagically"...

[techfg]

@vernak2539 -

Thanks for the thinking here. Yeah, I think we'd follow the starlight-links-validator approach exposing an Astro integration that internally contains a rehype plugin. Don't see a reason to have the plugin separately as it's Astro specific and couldn't be used anywhere else - at least not as currently written.

I poked around the Integration API and unfortunately, I'm not seeing a way to obtain collection information during build. I'm still trying to figure out a way though. If we're able to obtain collection information, we may be able to simplify approach configuration wise for #74. If we can't, then there is still value in being an Astro integration (e.g., to get Astro config trailingSlash, srcDir, etc. config values) but not much beyond that unfortunately.

All that said, I do think making this an integration instead of a straight rehype-plugin makes sense although there's not a ton of value to do so.