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

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

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.

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.

Changelog

v0.16.0 (2024-11-27)

Full Changelog

Closed issues:

• not the right path #62
• bug: markdown links to files outside of a content collection directory should not be transformed #57

Merged pull requests:

• fix: do not transform links outside of a content collection directory #58 (techfg)