astro-rehype-relative-markdown-links

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 residing at src/content/<content_collection>
3. You have a page that renders the above content collection at src/pages/<content_collection>/[...slug].astro

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)).

OS Support

Tested with Node.js v18 and v20 and Astro 2.x+.

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

Installation

Yarn

yarn add astro-rehype-relative-markdown-links

PNPM

pnpm add astro-rehype-relative-markdown-links

NPM

npm install 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],
  },
});

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

const options = {
  contentPath: "", // where you store your content relative to the root directory. default: 'src/content'
  basePath: "", // the base path of your astro project. should match path passed in astro config (https://docs.astro.build/en/reference/configuration-reference/#base). default: '/'
};

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

Debugging

Using Yarn in example (sorry).

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

# or

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

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.

Changelog

v0.8.0 (2024-03-19)

Full Changelog

Merged pull requests:

• Use Astro's sluggifier for wider coverage incl. special chars #9 (marcortola)