TypeScript icon, indicating that this package has built-in type declarations

0.13.1 • Public • Published


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/ with the content of:

[relative link](./

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](./

OS Support

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

  • [x] MacOS (Ventura)
  • [x] Windows (Windows 11)
  • [x] Linux (Debian 11)



yarn add astro-rehype-relative-markdown-links


pnpm add astro-rehype-relative-markdown-links


npm install astro-rehype-relative-markdown-links



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]],


Using Yarn in example (sorry).

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

# or

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


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

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/ would be transformed into /collection/dir. This functionality was applied to files both at the content collection root and content collection subdirectories.

In PR #17, applying this functionality to 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 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

Package Sidebar


npm i astro-rehype-relative-markdown-links

Weekly Downloads






Unpacked Size

42.6 kB

Total Files


Last publish


  • vernak2539