Obsidian Wiki-Links in Astro with a Remark Plugin

A small Remark plugin that turns Obsidian [[wiki-links]] into normal links at build time, with labels, heading anchors and a fallback for unknown targets.

Obsidian links notes with [[filename]]. Astro does not understand that; it expects normal Markdown links like [text](/path/to/page/). The content of my old site lived in Obsidian (published like this), and I wanted to keep writing native Obsidian links without rewriting them before every commit. The answer was a small Remark plugin that runs at build time.

The setup

  • Editor: an Obsidian vault with a content/ subtree mirrored into the Astro repository.
  • Site: Astro 6, static build, posts in .md and .mdx.
  • Goal: [[my-post]] becomes <a href="/blog/.../my-post/">my-post</a>, with no preprocessing step in the pipeline.

How Remark plugins work

Remark works on a Markdown syntax tree (MDAST). A plugin is a function that receives the tree and changes it in place. The node type that matters here is text: the raw text inside paragraphs, list items and headings. Wiki-links sit inside text nodes and have to be split out into link nodes.

Build the file index once

The plugin needs to know which file name belongs to which URL. Scanning the file system on every node would be absurd. Instead it scans the content folders once when the module loads and keeps a Map<filename, url>:

const SOURCES = [
    { base: resolve(__dirname, '../content/blog/posts'), urlPrefix: '/blog' },
    { base: resolve(__dirname, '../content/notes'), urlPrefix: '/notes' },
];

function buildFileIndex() {
    const map = new Map();
    for (const { base, urlPrefix } of SOURCES) {
        let files;
        try {
            files = readdirSync(base, { recursive: true });
        } catch {
            continue;
        }
        for (const file of files) {
            if (!/\.(md|mdx)$/.test(file)) continue;
            const slug = file.replace(/\.(md|mdx)$/, '').replace(/\\/g, '/');
            const filename = slug.split('/').pop();
            if (!map.has(filename)) {
                map.set(filename, `${urlPrefix}/${slug}/`);
            }
        }
    }
    return map;
}

const fileIndex = buildFileIndex();

One scan per build, then constant-time lookups.

urlPrefix has to match what Astro's router generates, not the folder structure. My blog loader used base: "./src/content/blog/posts", so slugs started with the year (2026/03/26/...) and the URL was /blog/2026/03/26/.... The files lived in a posts/ folder, but the URL had no posts/ segment.

Replace the text nodes

The plugin visits every text node, looks for [[...]] and, if it finds one, splits the node into text and link nodes:

visit(tree, 'text', (node, index, parent) => {
    if (!WIKI_LINK_RE.test(node.value)) return;
    WIKI_LINK_RE.lastIndex = 0;

    const nodes = [];
    let last = 0;
    let match;

    while ((match = WIKI_LINK_RE.exec(node.value)) !== null) {
        if (match.index > last) {
            nodes.push({ type: 'text', value: node.value.slice(last, match.index) });
        }

        const inner = match[1];
        const pipeIdx = inner.indexOf('|');
        const ref = pipeIdx === -1 ? inner : inner.slice(0, pipeIdx);
        const label =
            pipeIdx === -1
                ? ref.split('#')[0].trim()
                : inner.slice(pipeIdx + 1).trim();
        const [filename, heading] = ref.trim().split('#');
        const base = fileIndex.get(filename.trim());
        const url = base
            ? heading
                ? `${base}#${heading.trim()}`
                : base
            : `#${filename.trim()}`;

        nodes.push({
            type: 'link',
            url,
            title: null,
            children: [{ type: 'text', value: label }],
        });

        last = match.index + match[0].length;
    }

    if (last < node.value.length) {
        nodes.push({ type: 'text', value: node.value.slice(last) });
    }

    parent.children.splice(index, 1, ...nodes);
    return [SKIP, index + nodes.length];
});

Supported syntax:

Obsidian Renders as
[[my-post]] link with filename as label
[[my-post\|custom label]] link with custom label
[[my-post#heading]] link with #heading fragment

A file name that is not in the index falls back to #filename. The post still builds, the link just leads nowhere useful. A broken anchor is easier to spot than a missing link, and the build stays green.

Register the plugin

In astro.config.mjs the plugin goes into markdown.remarkPlugins. Astro applies it to .md and .mdx alike:

import { remarkObsidianLinks } from './src/lib/remark-obsidian-links.mjs';

export default defineConfig({
    markdown: {
        remarkPlugins: [remarkObsidianLinks],
    },
    // ...
});

Astro's content cache

Astro caches parsed content under .astro/. If you change the plugin after the content was parsed, the cached output is still served, even after restarting the dev server. I debugged the plugin for fifteen minutes before I realised none of my changes had any effect. Delete the cache:

rm -rf .astro

Then restart the dev server. The file index is rebuilt and every wiki-link is resolved again.

Takeaways

  • A plugin on the syntax tree is cheaper than preprocessing: one pass at build time, no extra files, no shell step in the pipeline.
  • Build the lookup index once when the module loads. Scanning per node only hurts once the vault grows.

More on this

Topic
  • Static Website A website made of finished HTML files that are built once and then served unchanged. No server code, no database.
Uses
  • Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.
  • Markdown Simple markup language for text. Files stay readable without special software and can be converted to HTML.
Mentioned in
  • My Old Astro Website My old site at adrian-altner.de: Astro with the Node adapter, typed content collections, IndieWeb features and photos as files with JSON sidecars.
See also

Show in the graph view →