Feb 28, 2024

Fix Obsidian URLs with Remark (Astro)

For those deeply invested in knowledge management and note-taking, Obsidian has become a cornerstone application. Its unique features and customizability cater to diverse workflows, but one challenge can arise when integrating Obsidian with a website: URL formatting discrepancies.

This blog post delves into the technical aspects of how to create a plugin designed to address this very issue. We’ll explore its functionality and implementation details.

Understanding the Challenge

Obsidian employs a specific markdown syntax for internal links, which can differ from the URL structures used on traditional websites. This inconsistency can lead to broken links when transferring content from Obsidian to a website, hindering the user experience and creating maintenance overhead.

The Remark Internal Url Fixer: A Solution

The remark Internal Url Fixer tackles this challenge head-on by seamlessly transforming internal URLs within your Obsidian notes to align with your website’s URL format. This plugin operates within the remark ecosystem, a popular toolkit for markdown processing.

Note: This code snippet does not problems with images. This is left as an exercise for the reader, but has a very similar fix.


  • Use [[Wikilinks]] is off
  • New link format is set to Absolute path in vault
  • Default location for new attachments is set to In subfolder under current folder

The code

Short and sweet:

1import { slugifyFileName } from "../utils/sitemap.util"; 2export const remarkInternalUrlFixer = () => { 3 return (tree: any) => { 4 function visit(node: any) { 5 if (node.children) { node.children.forEach(visit) } 6 if (node.type === 'link' && node.url) { 7 const isInternalLink = !node.url.includes('://') 8 if (isInternalLink) { 9 node.url = `/${slugifyFileName(decodeURI(node.url))}` 10 } 11 } 12 } 13 visit(tree); 14 }; 15}; 16export default remarkInternalUrlFixer;
  • remarkInternalUrlFixer: This function serves as the entry point, accepting a markdown document represented as a tree structure.
  • visit: This recursive function iterates through the entire tree, examining each node for relevant information. If a node possesses child elements, the function calls itself recursively to process them as well.
  • node.type === 'link': This condition checks if the current node represents a link element, indicating the presence of a URL.
  • !node.url.includes('://'): This conditional statement determines if the URL is internal. Internal URLs lack the protocol specifier (e.g., http or https) and are specific to your website’s structure.
  • node.url =/${slugifyFileName(decodeURI(node.url))}`: If the URL is deemed internal, the plugin rewrites it. This involves:
    • Decoding: Any encoded characters within the URL are decoded using decodeURI to ensure proper handling.
    • Slugification: The filename component of the URL is transformed into a slug format suitable for website URLs using slugifyFileName. This ensures consistency and adherence to your website’s URL structure.
    • Path creation: A forward slash (/) is prepended to the transformed URL, creating a valid website path.

This plugin should then be used with Astro/Remark like this:

1export default defineConfig({ 2 // ... 3 markdown: { 4 remarkPlugins: [remarkInternalUrlFixer] 5 } 6 // ... 7});

The Advantages of this plugin

By leveraging the remark Internal Url Fixer, you can:

  • Maintain your preferred workflow: Continue using Obsidian’s internal linking system without the need to manually adjust URLs for your website.
  • Effortless integration: The plugin operates silently in the background, automatically transforming URLs during the markdown processing stage.
  • Enhanced user experience: Visitors to your website will encounter only functional links, leading to a smoother and more positive experience.

Conclusion: A Bridge Between Obsidian and Your Website

The remark Internal Url Fixer demonstrates the power of custom plugins in enhancing Obsidian’s capabilities. By addressing the URL formatting discrepancy, this plugin fosters a seamless workflow for knowledge management and content creation, allowing you to leverage the strengths of both Obsidian and Remark.