Setting universal Markdown link shortcodes

[xplosionmind]

Markdown provides the great opportunity of creating link shortcodes/placeholder, as represented below.

[example](https://example.com 'Hey, I am an example!') is the same as [example]


[example]: https://example.com 'Hey, I am an even cooler placeholder example!'

How awesome it would be if I could provide to Eleventy a data file with a list of all the values in between the square brackets, their corresponding URL, and the title, so that I do not have to specify it on every single page, if it is a link I use often inside the vault?

example of what I envision, in /_data/links.csv, where name is [shortcode]:

title,name,url
Hello there,Hello there official website,https://hellothere.xyz
Howdy here,Howdy here brand,https://howdybuddy.co

[pdehaan]

Not exactly what you're looking for, but you seem to be able to use {% include %} and then put your reference style links into an include file in your src/_data/ directory (so at least you wouldn't need to duplicate a bunch of links on each page; as long as you don't mind maintaining a big-list-of-links in a single file).

---
# src/test.md
title: Test
---

[example](https://example.com 'Hey, I am an example!') is the same as [example]

{% include "links.md" %}

<!-- # src/_includes/links.md -->
[example]: https://example.com 'Hey, I am an even cooler placeholder example!'

OUTPUT

<p><a href="https://example.com" title="Hey, I am an example!">example</a> is the same as 
  <a href="https://example.com" title="Hey, I am an even cooler placeholder example!">example</a></p>

[pdehaan]

While it isn't CSV (since I was too lazy to install a module), it works w/ a JSON file in my src/_data directory.

src/_data/md_links.json

[
  {
    "title": "Hello there",
    "name": "Hello there official website",
    "url": "https://hellothere.xyz"
  },
  {
    "title": "Howdy here",
    "name": "Howdy here brand",
    "url": "https://howdybuddy.co"
  }
]

src/_includes/md_links.liquid

Convert the global data file into Markdown reference link syntax…

{% for link in md_links %}
[{{ link.name}}]: {{ link.url}} '{{ link.title }}'
{%- endfor %}

src/test2.md

---
title: test2
---

[Hello there official website]

THis is some more markdown.

And a link to [Howdy here brand]

{% include "md_links.liquid" %}

OUTPUT

<p><a href="https://hellothere.xyz" title="Hello there">Hello there official website</a></p>
<p>THis is some more markdown.</p>
<p>And a link to <a href="https://howdybuddy.co" title="Howdy here">Howdy here brand</a></p>

It "works", but you have to make sure you include the "md_links.liquid" file so the Markdown understands the links.
So far I haven't been able to get it to work w/ a shortcode. We may or may not be able to get it to work with eleventyConfig.addGlobalData() in Eleventy v1.0.0+ instead of a global data file, but if you're using Netlify admin, maybe a global data file is preferable.

[pdehaan]

Further down the rabbit hole…

LiquidJS deprecated {% include %} in favor of {% render %} which doesn't pass an entire global scope around, so we need to explicitly pass md_links (which is our global data file) to the src/_includes/md_links.liquid file if we want to be good citizens and not use deprecated APIs/tags:

---
title: test3
---

[Hello there official website]

THis is some more markdown.

And a link to [Howdy here brand]

{% render "md_links.liquid", md_links:md_links %}

And I also converted to a shortcode instead of an include file:

---
title: test4
---

[Hello there official website]

THis is some more markdown.

And a link to [Howdy here brand]

{% markdown_links %}

module.exports = function (eleventyConfig) {
  eleventyConfig.addGlobalData("md_links", [
    {
      title: "Hello there",
      name: "Hello there official website",
      url: "https://hellothere.xyz",
    },
    {
      title: "Howdy here",
      name: "Howdy here brand",
      url: "https://howdybuddy.co",
    },
  ]);

  eleventyConfig.addShortcode("markdown_links", function () {
    // `eleventyConfig.globalData` only contains data added via `.addGlobalData()` API and not files in src/_data directory.
    // If you want to put the links in an external md_links.json file, we probably just need to globally `require("./md_links.json")` somewhere in here.
    return eleventyConfig.globalData.md_links
      .map((link) => `[${link.name}]: ${link.url} "${link.title}"`)
      .join("\n");
  });

  return {
    dir: {
      input: "src",
      output: "www",
    },
  };
};

Not sure this solution is any better, exactly. But it did reduce the need for a global data file and an include file (at the expense of a potentially huge .eleventy.js config file if you expects dozens of reference links).

---

The thing I wasn't able to get working is including the {% markdown_links %} shortcode or include/render from within a layout file.
I think the current rendering pipeline doesn't work that way (which makes sense since we can have liquid layout files hand off to nunjucks layout files, etc).

[xplosionmind]

Wow, @pdehaan, you definitely are super helpful! Every time I got an answer from you, I am sure I will have a new great perspective. thank you very much.

Searching for something unrelated (link checking) I stumbled upon this Stack Overflow thread, that basically says the same thing.