Creating Obsidian Plugins

I don't use Obsidian that much because I'm busy using Confluence for work. However, like many others I was impressed with how my notes in Obsidian could be linked to or embedded in other notes. I felt as though I could express connections that formed between ideas as I thought them in my mind... even if I did not put much effort into doing so.

In spite of my general approval, I was dissatisfied with Obsidian's templating features. The core Templates plugin is basically a copy-and-paste operation with variables, so no changes in the template will propagate to the notes that were generated with the template.

To address this, I developed a plugin to integrate the Pug templating engine as a code block processor that dynamically renders HTML templates. I also created another plugin that integrates Tailwind CSS and automatically generates a stylesheet with atomic CSS classes that you use in your notes.

The pug-templates Plugin

Pug is a modest legacy templating engine, and it is commonly used with the Express web application framework. Crucially, Pug allows implements "mixins", or reusable templates that take arguments like functions, similar to snippets in Svelte. You may also supply another template as an argument for a mixin, similar to how web components may accept slotted content.

My pug-templates plugin installs a code block processor and renders all pug code blocks using Pug's JavaScript API. Additionally, since Obsidian allows you to declare front matter in each note, my plugin will make that front matter available as contextual data for the Pug template.

As an example, consider the following code:

---
title: Simple Test
summary: |
  This test demonstrates using the Pug templating language.
list:
  - one
  - two
  - three
---

```pug
h3= fm.title
p
  | #{fm.summary}
  | Most of this content comes from the page's front matter.
ul
  each val in ['one', 'two', 'three']
    li= val
```

This will produce the following content in your Obsidian note:

Simple Test

This test demonstrates using the Pug templating language. Most of this content comes from the page's front matter

• one

• two

• three

The plugin's GitHub repository has more details and some examples, so please check out nicholas-wilcox/pug-templates-obsidian-plugin if you're interested.

The tailwind-snippet Plugin

Maintaining CSS stylesheets is a pain in the ass, or at least it is when there is no framework to bundle CSS and scope it to different components and templates.

Obsidian's Vault API lets you create callback functions that trigger whenever a note is modified, so I created a plugin that ports Tailwind's PostCSS installation code and generates a stylesheet that contains the rules for all the Tailwind CSS classnames that you've used in your notes. You need to manually enable this stylesheet, but only once.

I've added some extensibility options that expose parts of the Tailwind API and also the APIs of some utility PostCSS plugins. You can find more information at the nicholas-wilcox/tailwind-snippet-obsidian-plugin repository on GitHub.

Tailwind CSS Versions

The recent release of Tailwind v4 includes a major performance upgrade, and this is supported in part by some natively compiled dependencies. I have been unsuccessful in trying to port my plugin to v4 because of some compilation errors. Unfortunately, it is beyond my expertise to reconcile the new Tailwind framework and the Obsidian compilation target environment.

Additionally, Tailwind has deprecated the ability to selectively disable their core plugins, including Preflight, which means that I need to redesign parts of my plugin if I want to upgrade to Tailwind v4. It seems like my plugin will remain compatible only with v3 unless some expert with extra time on their hands happens to stumble upon my code. 😅

Creating Test Vaults

While developing these plugins, I ended up with a general strategy for developing code-driven test vaults that demonstrate and validate a plugin's functionality. This strategy involves two parts:

1. I modify the default esbuild configuration code provided by Obsidian's template plugin repository, and in particular I add an esbuild plugin that creates a vault in the local development environment and copies the compiled plugin into that vault's plugin folder.

2. I include pjeby's hot-reload plugin as a git submodule so that it is also a plugin for the aforementioned test vault.

Ultimately, I have a way to create tests for my Obsidian plugins in the form of an Obsidian vault, and I can commit that vault's contents to my git repository so that other developers can easily test the plugin.