aka relative links, file path links. Software supports portable markdown links if for content like this:
[test](folder/test.md)
- 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.
Top comments (0)