Simplicity In Software: a Simple Example

The best solution to any problem is usually the simplest one.

I'm a big fan of simplicity in software design and implementation - and I recently implemented a small change that demonstrated this philosophy perfectly.

This blog (as well as Sitecore Spark) is run on my homegrown blogging engine, which means I get to add and modify features to make my life easier on a regular basis. One such changed involved image manangement.

The Problem

My blog posts are written in Markdown and converted to HTML for the web. Adding images to a post is an awful process:

• Upload an image to the admin backend
• Get the image URL for Markdown
• Get the image thumbnail URL for Markdown
• Populate the Markdown image tag as needed ([![]()]())

Using images in posts requires more steps than I'd like, plus I suck at remembering the exact syntax of Markdown image tags.

Here's a post with associated media available to it:

The (Almost) Solution

• "What if I just use a simple token to represent a media item?"

I love string replacement, so I started down the path of using simple tokens to represent media items in the Markdown:

{{codemash.jpg}}

With that, I'd modify the Markdown-to-HTML conversion process to replace that token with a complete HTML img tag. Users (i.e. me) no longer have to worry about writing a Markdown image tag with multiple image sources. Simple! Easy!

Except it wasn't.

• How do I supply alt and title text?
  • Maybe I use a pipe-delimited format in this tag?
• How do I add or remove the thumbnail version?
• This isn't a Markdown-standard tag, so this needs to be a documented customization.
• Where do I maintain image token IDs?
  • Is it time for a new database table?
• When images are deleted/moved, when and where do I re-sync tokens?

So yeah, this "simplification" blew up fast. I hated it before I even finished the prototype. I've never done a git branch -D so fast.

The (Simple) Solution

I was trying to solve the right problem the wrong way. Using a custom token format deviates from Markdown so much that it trades one problem (Markdown complication) for another (non-standard Markdown syntax).

The final solution was much simpler in every way: a dedicated button that provides a complete Markdown image tag that can be dropped into a blog post:

That button produces this Markdown syntax, ready to be dropped into the post:

[![ALT](/media/2023/d8c48e7a43b1/codemash-thumb.jpg)](/media/2023/d8c48e7a43b1/codemash.jpg)

The benefits were obvious:

• No custom token to learn
• Flexibility to customize images further
• No complicated backend token management
• Simple implementation (just a front-end change)

Once again: the best solution is usually the simplest.