feat(links.ts): custom identifiers for custom icons

[bfahrenfort]

{ I am pathologically incapable of rebasing, apparently -- #1653 }

This feature gives site authors more control over how links are displayed. You can define a regex that, on match, will auto-append either a string of your choice (so, an emoji) or a Hast element such as a vector path or an image to the link in the rendered HTML.

As an example, I have a substitution:

[
  /Qx!(.+)/, // Qx!https://quartz.jzhao.xyz
  Image("/static/external-quartz.png"), // I went into paint and magic wand deleted the background of the Quartz favicon
]

Which for [Quartz](Qx!https://quartz.jzhao.xyz) yields:

which links to the correct website as specified in the capturing group.

changes:

• switch from requiring manual hast to newtypes for the three most common use cases: Image, Path, or Emoji
• discuss -- should this be as freeform as a regex, or should it be constrained to a prefix for better ergonomics and a lower barrier to entry?
• documentation
• favicon newtype - see the pond: transformers/AddFavicons
  • behavior: if Favicon() is a replacement, then links matching that regex will attempt to fetch their favicon and put it after the link. Could also set this to automatically attempt for all links like the plugin linked as inspiration, but I'd also like to expose it as optional per-link should the author define a substitution like [/f!(.+)/, Favicon()]

[saberzero1]

Please do not use var. Prefer const where possible, otherwise use let.

var's initialization is moved to the top of the scope, but the value assignment is not, leading to unexpected behavior.

function varExample() {
  console.log(test); // undefined
  var test = "hello";
  console.log(test); // hello
} 

function letExample() {
  console.log(test); // error: test is not defined
  let test = "hello";
  console.log(test); // hello
} 

[bfahrenfort]

@saberzero1 thanks for reminding me, functional programmer with an automatic conception of let here haha

[aarnphm]

My feeling with this, while very powerful for folks with programming coherency, makes non-programmer a bit overwhelmed.

fwiw afaict we want to have an easier way to add hast element towards link processing.

Regardless if we want to add more elements to links, I wonder if it makes more sense to just have this as an example of how to do this, while keep the core lean and maintainable

my fear is that we essentially have a separate dsl for this while ppl who alr modify components for quartz are more familiar with hast-way of doing things.

I'm also fine if we make this into a separate rehype transformers item. Just my two cent.

[bfahrenfort]

Yes, I want to refactor to make it easier and put all the raw hast under the hood. To let the author just pass the string they want and let it be picked up as the type of content that it is, I'm experimenting with tagged types as a newtype implementation but will probably have to settle for discriminating unions with type guards, same approach as in my RSS PR.

[bfahrenfort]

One half of the syntax for the feature is now more ergonomic. side note--I found unintended behavior in links.ts, removed a dependency based on sindresorhus/is-absolute-url#17, and fixed the bug.

I'm open to suggestions on whether how to specify what links you want to trigger the substitution should be simplified too. One option would be to force that it can only be a prefix, meaning the author passes a string rather than a regex and the plugin uses startsWith and slices to implement. Thoughts? That would mean a Sub looks like:

[ "Qx!", Image("/static/external-quartz.png") ] // For links to other sites that use Quartz

Of course, the tradeoff is less freedom of the author to decide how they want to say "make this link look different to the others" when they're writing their markdown content. I can see a use case for regexes in matching specific links to automatically use a certain type of icon, which would be lost.

Or I could do another discriminating union that can use either a Prefix("Qx!") or a RegExp, lol