Portable markdown links

stereobooster - Sep 22 '23 - - Dev Community

aka relative links, file path links. Software supports portable markdown links if for content like this:

[test](folder/test.md)
Enter fullscreen mode Exit fullscreen mode
  • For editor : user can Cmd + Click the link and editor will jump to that file
  • For static website generator : file pahts are replaced by URLs according generation scheme, for example: [test](folder/test.md)<a href="/folder/test/">test</a>

Example

portable-hugo-links shows how same links work in Github and website generated by Hugo.

Features

  • Links: [readme](/readme.md), which also includes resolution of relative and absolute paths:
    • [readme](../readme.md)
    • [readme](./readme.md)
    • [readme](readme.md)
  • Anchors: readme
    • for editor: Cmd + Click should navigate to specified section
    • for static website generator: anchors should be preserved in html links
  • Images: ![alt]_(img.jpg)
    • for editor’s preview: images should be displayed
    • for static website generator: images should be displayed

Who supports it?

Software Does it support PML
Github Yes
VSCode Yes
Hugo Yes, with configuration
Obsidian Yes
Docusaurus Yes, see documentation
Markdown Language Server Yes
markdown-links Yes
Jekyll Yes, with plugin
Astro No, see discussion
Next.js No, AFAIK
Gatsby No, AFAIK

Naming

Why do I call it portable? Because this simple convention allows to use same markdown files with different software wihtout modifications. In the same vein, we can think of portable markdown frontmatter, etc.

A bit of convention over configuration goes long way.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .