Skip to content

vernak2539/astro-rehype-relative-markdown-links

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

6df53c4 Â· Dec 19, 2024
Dec 19, 2024
Dec 19, 2024
Dec 3, 2024
Dec 12, 2024
Dec 19, 2024
Apr 16, 2024
Dec 19, 2024
Apr 15, 2024
Dec 3, 2024
Dec 12, 2024
Jan 31, 2024
Dec 5, 2024
Dec 19, 2024
Dec 19, 2024
Dec 19, 2024
Dec 11, 2024
Dec 19, 2024

Repository files navigation

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.