some cat blog

wikilinks + image embeds in 11ty

2025-05-29T14:01:00Z

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

custom emoji in 11ty with a plugin

2025-05-18T14:51:00Z

hey i did a thing: markdown-it-emoji-customizer

it's a plugin for 11ty, as a helper module for markdown-it-emoji, so it's possible to easily have custom emoji/icon shortcodes!

it:

takes in your md library from 11ty
scans a dir for custom emoji images
makes the definitions (the shortcodes and info about what image the shortcode refers to)
optionally also converts shortcodes for standard unicode emoji to their unicode equivalent
makes an <img> with custom attributes for the custom emoji, wrapped in a <span> with a custom class (specific to these custom emoji image spans)
wraps the unicode emoji that were converted from shortcode (if any) in a <span> with a custom class name (specific to these unicode emoji spans)
also includes some (optional) basic css snippet to try to make the custom emoji and unicode emoji a bit more uniform in appearance (at least on my site, on my device lol)
returns the modified md library

so when the site is built, if you have some markdown like:
:cat: :arrow_left: *unicode!*
:neocat: *custom!*
you'll get something like:

🐱 ⬅️ unicode!
custom!

Heart

much thanks and shoutout and meowing to volpeon for making custom emoji sets that are so good i was compelled to create this plugin to use them here!
(neocat emoji license: CC-BY-NC-SA-4.0)

blog - obsidian templates and use

2025-05-05T18:50:00Z

intro

by using the obsidian plugins QuickAdd and Templater, i can quickly make draft posts and later promote them to regular blog posts.

warning

this is my "opinionated" way to do it, a bit silly, and there are other ways to do it, but c'est la vie.

QuickAdd setup

in QuickAdd i use a template (detailed below) with the following options:

this creates a new draft in /blog/drafts/, using a template creatively named _obsidian_templates/blog_post_draft.md.

executing this action prompts for a filename (the bit after the date and separator), resulting in something like /blog/drafts/2025-05-05 - some post.md.

the draft opens in a new focused tab in obsidian, after some prompts.

the filename then gets used by the template to determine the frontmatter title (more information in the next section).

new draft template

this template (blog_post_draft.md) used by QuickAdd (above) has the following frontmatter block:

---
title: <% tp.file.title.split(" - ").slice(1).join(" - ") %>
date: <% tp.date.now('YYYY-MM-DDTHH:mm') %>
modified: 
description: {{VALUE:description}}
tags:
<%*
	let tagsArray = `{{VALUE:tags}}`.split(",").map(tag => `  - ${tag.trim()}`);
	tR += tagsArray.join("\n");
%>
---

breaking it down:

title

title: <% tp.file.title.split(" - ").slice(1).join(" - ") %>

this takes the filename and turns it into the title.
the split and slice and join is to split it all by instances of - (space dash space), slice off the first section, then join the remaining pieces with - (space dash space).

the reason i'm doing this is because i want all of my drafts and posts to have a filename of YYYY-MM-DD - title.md (my preference, supported by the way i have QuickAdd create the files), but i also want to be able to have a space dash space in the title itself, if desired, and i don't want the date to be in the title.

this means that something like
2025-05-05 - a post - part two.md
would result in frontmatter like
title: a post - part two

it's a personal choice and method for how i like to do filenames and titles.

what about regex?

no.

date

date: <% tp.date.now('YYYY-MM-DDTHH:mm') %>

this just inserts the current datetime in the date field.

modified

this is left null on draft creation.
it gets populated automatically with the obsidian plugin update modified date as the content of the draft (or published post) is modified over time, in the same format as the date.

description

description: {{VALUE:description}}

this is one of the prompted fields, filled in at time of draft creation. just a string.

frontmatter result

for the draft of this post, the raw frontmatter after creation might be like:

---
title: blog - obsidian templates and use
date: 2025-05-05T12:00
modified: 
description: about the templates i use in obsidian to create drafts and posts
tags:
  - blog
  - obsidian
  - templates
---

(the modified value will get automatically updated as the post is worked on)

promoting drafts to posts

again, this is all very silly, but:

with a draft open and focused, i run the following template (_move_draft_to_blog.md) via key combo (alt + e):

<%*
// update the frontmatter with the current date
tp.hooks.on_all_templates_executed(async () => {
  const file = tp.file.find_tfile(tp.file.path(true)); // the (t)file
  await tp.app.fileManager.processFrontMatter(file, (frontmatter) => {
    frontmatter["date"] = tp.date.now("YYYY-MM-DDTHH:mm"); // update 'date:'
    frontmatter["modified"] = null; // null 'modified:'
  });
});

// move the post into '/blog/' with appropriate filename
await tp.file.move("/blog/" + tp.date.now("YYYY-MM-DD") + " - " + tp.frontmatter.title);
%>

this:

moves the file from /blog/drafts/ into /blog/, renamed with the current date (like 2025-05-05 - title.md)
updates the date value to the current date
nulls the modified value

the point of this is so that if i start a draft last week and promote it to a post today, it will be named and dated with today's date and a blank modified date.

this is so that a post's filename and date will be when it was published, not when it was drafted, and so that the modified won't be a time before the post was published (and modified won't be present at all on the blog, initially, as it doesn't show when null)

modifying the post after it's officially a post will of course update the modified value automatically, thanks to the obsidian plugin for handling that.

why not just manually move the file instead of doing this?

i need the filename, date, and modified to change and don't want to manually do it (read: automatically forget to do it)

outro

silly, sure, but a working kind of silly and working in a way i like.

i launch the QuickAdd action, fill in the info when prompted, start writing the draft.
i launch the templater action to promote it to a post with updated filename and date.
done.

i could likely do the draft to post promotion part through QuickAdd as well but to be honest i got it working this way and stopped messing with it.
that being said:

Note

this method might change in the future and if so i will make a new post about whatever new silliness i'm doing then.

links

obsidian plugins mentioned (github links):

blog setup

2025-05-04T09:11:00Z

intro

i wanted to be able to

make posts in obsidian in a "normal (for me)" way (wikilinks, image embeds, callouts, etc)
have the obsidian vault be a part of the (dev) repo for an 11ty blog
make it work

at times it felt like this was going to be a "pick two" kind of situation but it's more or less working (for) now, with potentially more future expansion.

below are some notes and links and explanations about this setup.

11ty

this is an 11ty project, based on the 11ty base blog starter.

plugins

my style of obsidian use was facilitated through a combination of several markdown-it related plugins (listed here in no particular order):

markdown-it

github link: markdown-it
for markdown.

markdown-it-attrs

github link: markdown-it-attrs
for adding attributes to elements via markdown.

markdown-it-link-attributes

github link: markdown-it-link-attributes
for adding link attributes (target="_blank", classes, etc)
pretty sure the plugin before this could handle this also, but i think it would require i manually add the attributes to links in obsidian every time (or do some more templating and link processing on the 11ty side) and i do not want to do that.

markdown-it-obsidian-callouts

github link: markdown-it-obsidian-callouts
for making the obsidian markdown callouts work, with optional styling via css.
see also: this test post with some callouts and codeblocks: testing

markdown-it-prism

github link: markdown-it-prism
for prism syntax highlighting within markdown code fences

markdown-it-task-checkbox

github link: markdown-it-task-checkbox
markdown-it plugin for adding github style task lists with classes and ids.

markdown-it-mark

github link: markdown-it-mark
for converting markdown highlights to <mark> markup.
==example== becomes example

markdown-it-toc-done-right

github link: markdown-it-toc-done-right
for adding a table of contents into posts, triggered via putting [toc] in the markdown of a post.

markdown-it-emoji-customzier

github link: markdown-it-emoji-customizer
for converting custom emoji shortcodes (:neocat: etc) to <img> tags, as well as unicode emoji shortcodes (:cat: etc) to unicode-emoji-wrapped-in-<span>. has options.
intended to work with (but doesn't require!) the obsidian-icon-shortcodes Obsidian plugin (mentioned in next section)
see also: this post

markdown-it-wiklinks-plus

github link: (not yet)*
diy plugin for converting wikilinks ([[some post]]) and wikilinks image embeds (![[image.png]]) using markdown-it tokens rather than regex. i was originally using two other existing plugins (which used regex...) for both of those things but they were conflicting with each other so i rolled my own using markdown-it tokens. has many options.
*(not available yet because i want to do more testing with 11ty/obsidian setups that aren't like mine)

markdown-it-anchor

github link: markdown-it-anchor
for putting the link icon before headers

theme

the theme is using bits of the catppuccin palettes (some latte and mocha) and the laserwave prism theme for codeblocks.

obsidian

i really like obsidian and it was important to me that i not have to compromise too much on "my obsidian way" of doing things to make the blog posts. the collection of plugins above for eleventy (plus relevant options configuration) mostly covered that.

plugins

i use a few obsidian plugins to make this all easier or possible. a few of them are strictly "user experience" sort of things that have no relevancy in the actual obsidian to eleventy pipeline, so they will not be listed. the relevant ones, in no particular order, are:

templater

github link: templater
templater is very powerful and key to starting my drafts and "publishing" them, combined with QuickAdd (below).
i have two templater templates: one to create a draft with prompts for the desired frontmatter in place (like title, description, tags) which creates the draft with a filename based on the current date + the prompted title (eg 2025-01-01 - title), and one to simply move a draft from my drafts/ folder into the base blog/ and update the frontmatter date and filename accordingly (eg the previous draft if "published" the next day becomes 2025-01-02 - title with matching date: and a null modified: frontmatter).

quickadd

github link: quickadd
quickadd uses the template for a new draft to create the file itself and apply the template (which prompts for the data).

update modified date

github link: update modified date
this can automatically update a chosen frontmatter key when the file content has been modified in obsidian. i prefer this over using any kind of actual raw/git file modification timestamps because i only want the modified: frontmatter to change when the content of the post changes. going by git/filesystem modified dates could be problematic, for that goal. modified date is nulled when a post is promoted from draft to proper blog post (this way i don't have modified dates on published posts that are prior to publishing date, no modified date, yet i can still keep track of modified dates while in the draft phase, and modified date automatically changes if i edit a post after publishing it).

obsidian-icon-shortcodes

github link: obsidian-icon-shortcodes
this is for shortcodes in Obsidian (:shortcode:). has autocomplete popup, supports custom emoji in 'packs'.

hosting

i am pushing the built site to a github pages configured repo, using the gh-pages npm package.

notes and thoughts

there are options for pushing the blog to the repo from within obsidian, triggering a build, etc, such as the various git plugins or the buttons plugin or just shell scripting, but i prefer to have that as a manual separate step.
i could also use github actions but i do not want to.

TODO (maybe)

make this setup a barebones 11ty+obsidian blog starter template?
post the templater template for drafting new posts?
improve this post a bit

testing

2025-05-01T00:00:00Z

meow.

code blocks

code blocks (fences) with syntax highlighting (via prism).
some css:

main {
  content: "meow";
  color: #AAA;
}

some html

<html>
  <body>
    <span class="meowing">meow</span>
  </body>
</html>

callouts

callouts are written in obsidian in standard callout form and use lucide icons, like

> [!info] info callout test
> info callout

some callouts

info callout test

info callout

tip callout test (collapsable, default open)

tip callout

warning callout test (collapsable, default closed)

warning callout

success callout test

success callout

error callout test

error callout

bug callout test

bug callout

(more callouts available)

meow meow

2025-04-25T12:00:00Z

main {
  content: "meow";
}

meow

a test

this is a link to the meow world post, aliased as test
the above link in the markdown is [[meow world|test]]

callout

Info

test callout
with an internal link to meow world

meow world

2025-04-24T16:25:00Z

meowmeowmeow

i am currently in eleventy