astro-rehype-relative-markdown-links

This is a rehype plugin built for Astro that aims to transform relative links in MD and MDX files into their final output paths.

🚨 This is experimental and build exclusively for Astro. I have made a couple assumptions. They are:

1. You are rendering a static site (i.e. not using SSR)
2. You have a content collection(s) residing at src/content/<content_collection(s)>
3. (Fixed v0.17.0) You have a page that renders the above content collection at src/pages/<content_collection>/[...slug].astro
   • You can now map your content collection to paths that don't match your content collection directory name. See docs for more information.

Example Functionality

If you have a markdown files at src/content/blog/post.md with the content of:

[relative link](./other-markdown.md)

The resulting HTML should be:

<a href="/blog/other-markdown">relative link</a>

It supports links with Query Strings and Hashes (e.g. [relative link](./other-markdown.md?query=test#hash)).

Installation

yarn add astro-rehype-relative-markdown-links

Usage

astro.config.mjs

import rehypeAstroRelativeMarkdownLinks from "astro-rehype-relative-markdown-links";

// ...everything else

export default defineConfig({
  // ...everything else
  markdown: {
    rehypePlugins: [rehypeAstroRelativeMarkdownLinks],
  },
});

Configuration Options

See documentation for more information on the available configuration options.

To set custom options, pass an object to the plugin like below:

const options = {
  // ...
};

export default defineConfig({
  // ...everything else
  markdown: {
    rehypePlugins: [[rehypeAstroRelativeMarkdownLinks, options]],
  },
});

OS Support

Tested with Node.js v18, v20, v22 and Astro >=2 <6.

• MacOS (Ventura)
• Windows (Windows 11)
• Linux (Debian 11)

Notes

• I'm currently using this in my blog. Use it as an example if it's easier!
• This rehype plugin was called rehype-astro-relative-markdown-links in the past. I've changed this due to rehype's naming guidelines.

Debugging

Using Yarn in example (sorry).

DEBUG=astro-rehype-relative-markdown-links yarn build

# or

DEBUG=astro-rehype-relative-markdown-links yarn dev

Versions including and after v0.9.0

In PR #3 (based on issue #2), special case handling of index files was added where the index would be stripped from the URL. For example, src/content/collection/dir/index.md would be transformed into /collection/dir. This functionality was applied to index.md files both at the content collection root and content collection subdirectories.

In PR #17, applying this functionality to index.md at the collection root was removed based on the way Astro handles content at site/collection root vs. subdirectories (see this issue).

If you want to have your collection root index.md be transformed without the index slug, utilitize the slug frontmatter option provided by Astro setting your slug to empty string ('') and ensure your getStaticPaths() returns undefined for the slug of the content collection root index.md.