Skip to main content

Portable markdown links


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

  • 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/ β†’ <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](/, which also includes resolution of relative and absolute paths:
    • [readme](../
    • [readme](
    • [readme](
  • 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

Motivation #

Let’s say we have file /contnet/posts/

It can have following web links:

It can have following wiki links:

  • [[intro]]
  • [[posts/intro]] (in Foam for disambiguation)
  • theoretically with configs:
    • [[my-first-post]] (with slug: my-first-post)
    • [[Intoduction]] (with title: Intoduction)

It can have following portable links:

  • absolute: /contnet/posts/
  • relative: ./posts/, posts/, ../

To resolve web links you need:

  • configuration for resolution, something like (path) => "content" + path + ""
  • maybe root of the project
  • maybe scan all files in the root if there are tricky frontmatter configs used, like url, slug, permalinks, aliases

To resolve wiki links you need:

  • to know root of the project
  • scan all files in the root to be able to match name (file name or slug) to wiki link

To resolve portable links you need:

  • to know root of the project
  • to know file path where link is located (to resolve relative links)

To resolve web links you need:

  • to do nothing, but there is a chance that this will be 404 link or none-canonical link

To resolve wiki links you need:

  • resolve to file path first
  • follow the same procedure as for portable links

To resolve portable links you need:

  • read frontmatter of the file
  • generate link according to permalinks configuration

Who supports it? #

SoftwareDoes it support PML
HugoYes, with configuration
DocusaurusYes, see documentation
Markdown Language ServerYes
JekyllYes, with plugin
FoamYes, but bugy
AstroNo, see discussion
Next.jsNo, AFAIK
GatsbyNo, 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.

Read more: BEOE, Astro diagrams