Using markdown wiki-links in Astro framework

Question

I'm building a website using the Astro framework, and I want to use Markdown wiki-links (links formatted like this [[link to post]] from Obsidian to link to other pages on my site. For example, I want to be able to write [[Page Name]] in my Markdown content and have it automatically converted to an HTML link to the page with that name.

What is the easiest and/or right way to accomplish this in Astro? Is there a built-in way to parse Markdown wikilinks, or do I need to use a third-party library? And how can I integrate this functionality into my Astro theme?

I tried using remark plugin, wiki-link-parser etc., but had trouble making it work.

Any help would be greatly appreciated! Thanks in advance.

Answer 1

As I am also maintaining a blog website using Astro and managing blog contents of my site using Obsidian, my experience might be of some help.

Difference between Obsidian and Astro's markdown parsers

To begin with, I will show the difference between Obsidian and Astro's markdown parser.

• Obsidian. Obsidian adds a few useful syntaxes to the CommonMark Specs, including wikilinks and callouts. Obsidian's markdown parser (though close-sourced) is able to parse these elements and turn them into proper HTML.
• Astro. On the other hand, Astro's markdown parser is the open-sourced remark. Remark is written according to the CommonMark Specs, and therefore it does not support wikilinks. However, remark is extensible, and we can add some plugins to them make it support customized wiki link syntax.

So the main challenge here is to get a plugin of remark that can add wiki link syntax support to remark. Fortunately, you would be able to find one existing plugin @portaljs/remark-wiki-link.

Add @portaljs/remark-wiki-link into Your Astro Project

After installation of this plugin, to make @portaljs/remark-wiki-link work, you also need to configure it. My suggestion is that

• either you pass all pages' urls to this plugin's permalinks option, from which it can find the correct page url corresponding to Page Name in your wiki link [[Page Name]];
• or use absolute wiki link paths in Obsidian, and make this plugin auto-generate the url of [[Page Name]].

I have chosen the second approach, because it is more convenient. Here I post the related code segment inside astro.config.mjs file:

import { defineConfig } from "astro/config";
import wikiLinkPlugin from "@portaljs/remark-wiki-link";

// Here I assume your pages' urls are of format
// https://yourwebsite.com/posts/slug
// where slug is the slug of your markdown content
const pageUrlPathPrefix = 'posts/';

export default defineConfig({
  markdown: {
    remarkPlugins: [
      [wikiLinkPlugin, { 
        pathFormat: 'obsidian-absolute', 
        // generate url of the linked page.
        // here `slug` would be "Page Name" for wiki link [[Page Name]].
        wikiLinkResolver: (slug) => [pageUrlPathPrefix + slug] 
      }],
    ]
  }
});

Inside Obsidian, you will need to do:

1. change your wiki links in Obsidian into absolute format.
2. make sure that Page Name inside [[Page Name]] be the slug of the page you link to.

   Note that in Astro, markdown file name does not equal to the slug of that markdown file.

After the steps above, things should work. You can refer to the official documentation of this plugin for more information.

There are also other custom syntaxes of markdown in Obsidian, e.g. callouts. If you also want to make Astro parse callouts, I recommend you to check my plugin remark-callout.