wikilinks + image embeds in 11ty

contents:

hey i did a thing again: markdown-it-wikilinks-plus

it's another plugin for 11ty with markdown-it!

the situation

so this blog is made with 11ty and i use Obsidian as my cms basically.
i write posts in obsidian and my obsidian vault is part of the 11ty environment.

in obsidian, i use the default shortest path when possible option for new links (in obsidian settings > Files and links > New link format) and my filenaming conventions for posts and image embeds means i never really have to worry about duplicate filenames so my links and image embeds are always just [[name of note]] and ![[name of image.png]] or whatever, simple. it works for me.

at first i was using two 11ty/markdown-it plugins for handling wikilinks and image embeds, but they were both doing regex on somewhat-similar things so hmm

so this is a plugin that uses the markdown-it api (token and parsing stuff) rather than regex to detect wikilinks and image embeds and convert them to html, with some options!

the format

in obsidian, wikilinks can have a link label (the text of the link) by putting it after a pipe in the link.
also, image embeds can have alt text and/or display dimensions by putting a pipe after the image filename:

examples

[[some page|see here]]
- link to some page with link text see here
![[image.png|some cat]]
- image embed with alt text some cat
![[image.png|200x200]]
- image embed with display dimensions 200x200 (in obsidian)
![[image.png|some cat|200x200]]
- combo! alt text and dimensions!

about pipes

"but cat, what about if i wanna put some pipes in my link label?"

go ahead!

for wikilinks, this plugin uses the first pipe as a divider between the link target and the link label and includes any other pipes (if any) as part of the link label text!

example

for a wikilink like [[some page|label | with | pipes]]:

link label would be label | with | pipes

"but cat, what about--"

you can put them in the image embed alt text too!

the plugin checks the last pipe section in image embeds to see if it's dimensions or not.

if the last pipe section is not dimensions, everything after the first pipe is the alt text!
if the last pipe section is dimensions, everything between the first and last pipe is the alt text!

example

for an image embed like ![[image.png|alt | with | pipes|200x200]]:

alt="alt | with | pipes"
style="width: 200px; height: 200px;"

features

the plugin can convert wikilinks to <a> links (with link label) and convert image embeds to <img> (with alt text and/or dimensions, if either or both are included).
dimensions get used as an inline style attribute (width and height) on the <img>.

it can also insert an alt text attribute for image embeds that don't have any!

default alt text

the imageEmbed.defaultAltText option can be either a boolean or a string.

if it's true, any image embeds that are missing alt text will get the image name as the alt text. not a great placeholder tbh.

if it's a string, any image embeds that are missing alt text will get the provided string as the alt text. this might be useful if you want some easy to find placeholder to do stuff with. this also means it can take an empty string ('') to give image embeds with no alt text an alt="", which could be useful.

options

yep!

for wikilinks and/or image embeds, there are options for, among other things:

setting the absolute base URL and relative base URL
forcing all the links/embeds to be absolute pathing
doing custom post processing of targets and link labels and alt text
adding a uri suffix
adding custom html attributes
allowing link label formatting
- like [[some page|a *neat* link]]

my use

in my options, i force all links and image embeds to be absolute pathing and give my absolute base URL (/blog/ for wikilinks, /blog/assets/images/ for image embeds), give the wikilinks a class: 'internal-link' and image embeds a class: 'image-embed', and give image embeds a defaultAltText: '' so any images without alt text get a alt="" attribute.
works for me

final thoughts

meow