markjgsmith

When you are creating documents over and over again, whether it be a document, blog post or configuration files, by copying an old one and deleting/updating the old contents. That's a very error prone process, from getting the file naming, and location right, to ensuring consistent formating throughout.

Wouldn't it be great if there was a repeatable generation process for any text file? Well that's what templates are for, they can eliminate friction and ensure consistency across everything you write.

Also wouldn't it be great if there was a easy going file format for content creation, that wasn't too complex, with just enough syntax to write basic documents. And wouldn't it be great if there was a way to attach arbitrary meta data to these documents which you could use in all sorts of interesting ways, including seamlessly flowing them through LLMs/AI? Well that's what Markdown and Frontmatter are for.

We are going to look at all 3 of these things.

Templates

First let's demystify templates, what they are and how to use them.

A template is a skeleton file containing static structure combined with placeholder dynamic data.

Here's a basic example:

Template source (src/template/hello.hbs):

This example uses the handlebars templating language:

Hello {{recipient}}!

Here are your tasks for today:
{{#each tasks}}
- {{this}}
{{/each}}

Data file (data.json):

{
  "recipient": "World",
  "tasks": [
    "Review pull request",
    "Update documentation",
    "Publish blog post"
  ]
}

You can then render the template by running the cli:

$ handlebars src/templates/hello.hbs -d data.json -o output.txt

To get the following output (output.txt):

Hello World!

Here are your tasks for today:
- Review pull request
- Update documentation
- Publish blog post

Notice how not only has the recipient variable has been replaced by the corresponding value from the data file, but also that the template rendering process has iterated over all the tasks in the data file using the #each loop and inserted them into the template.

You can use templates for virtually any text format: source code scaffolding, configuration files, daily notes, and blog post drafts just to name a few.

You typically execute templates in one of two ways:

1. Via CLI commands: Executed directly in your terminal to quickly scaffold new files and automate workflows. You would need to install a community built CLI such as hbs-cli.

2. Programmatically: Integrated via libraries and packages in various programming languages to generate files dynamically within software.

There are many template languages, here are some of the most popular:

• Handlebars: A popular logic-less templating engine using braces {{ }} and block helpers like {{#each}}, serving as a robust default for many text-generation tasks.

• EJS (Embedded JavaScript): Uses standard JavaScript syntax inside tags (<% %>) for simple scriptable templating.

• Pug (formerly Jade): Focuses on clean, indentation-based syntax to write concise HTML structures without closing tags.

• Twig: A robust, feature-rich templating engine widely used across PHP ecosystems.

The point is that templating is a mature technology that has many different implementations. You don't need to learn all of them. You will normally settle on one based on both your personal experience with programming languages and perhaps the domain you will be operating in.

To give you a sense for the universal utility of templates, here is how they can fit in across industries, they aren't just for software engineers. They can streamline repetitive text creation for any professional or industry:

• Software Engineering & DevOps: Scaffolding microservices, Kubernetes manifests, boilerplate configuration (.env, CI/CD pipelines), and API documentation.

• Writing & Content Creation: Standardizing blog post layouts, newsletter issues, video production scripts, and editorial checklists.

• Business & Operations: Generating client invoices, project proposals, meeting agendas, weekly status updates, and customer support responses.

• Legal, Finance & Healthcare: Auto-filling standard contract clauses, compliance reports, patient intake structures, and recurring financial statements.

• Personal & Knowledge Management: Structuring daily log entries, workout trackers, travel planning sheets, and book summaries.

Markdown

Markdown is a text file format that implements the most common text formating features you actually need when writing, like headings of different sizes, bold or italic text, numbered lists, bulleted lists, hyperlinked text. Checkout this cheatsheet for the full feature set.

Here is an example markdown file:

# Building Portability First

When constructing workflows, **simplicity** is key. 

Key principles:
- Keep files flat and readable
- Store metadata near the content
- Rely on unix primitives

For detailed dotfile examples, visit github.com/mjgs/dotfiles.

<div class="callout-box">
  <p>HTML elements like this pass straight through to rendered output!</p>
</div>

It's a little odd to look at initially, but what you'll find is that very quickly you are able to parse full markdown documents as if they were typical text documents. They strike just the right balance of text and markup language. And most often you will be editing them in Markdown editors in any case, that render a beautiful UI ontop of them, and you can switch between the raw markdown and the nicely rendered text with one click or a button press. It's nice to know that no matter what, you can move them to any system and at least bee able to read them with a classic text editor. They are extremely portable.

With markdown you can keep your focus on content rather than on styling tags.

One of the other nice things about markdown is the HTML pass-through. Markdown files are very often rendered to HTML. A key feature is its flexibility: you can drop plain HTML directly into the text file (as shown above), and it passes straight through to the rendered HTML page whenever you need custom control.

Also with markdown files you get AI-native readiness by default. Because LLMs are trained extensively on plain text and Markdown, your notes, posts, and documentation are instantly readable and processable by AI tools without custom parsing layers.

Frontmatter

Frontmatter acts as a structured metadata layer at the very top of a plain text document (typically using YAML, TOML, or JSON enclosed in triple-dash --- delimiters).

Here's an example markdown file with YAML frontmatter:

---
title: "Templates, Markdown, and Frontmatter"
date: 2026-10-31
draft: false
tags:
  - workflow
  - markdown
  - handlebars
author: mjgs
---

# Building Portability First

Here is where the body prose begins...

While it shines brightest when paired with Markdown, frontmatter can augment many different text file formats by injecting variables, dates, titles, tags, and status flags.

Some practical applications of metadata:

• Website & Static Site Generators: Tools extract frontmatter to generate tags (page title, SEO meta tags, social sharing cards), populate layout navigation, render publication dates, and filter content by categories or tags.

• Content Querying & Indexing: Build dynamic archive pages, search indexes, or tag clusters based on frontmatter properties without having to parse the full body prose.

• Publishing Workflows: Automated build scripts can check flags like draft: true to skip unpublished posts during site generation or deployment pipelines.

There is broad ecosystem support for both markdown and frontmatter, from static site generators and web frameworks (Hugo, Jekyll, Astro, 11ty) to knowledge management and note-taking apps (Obsidian, Logseq), to headless CMS' and flat file platforms (Decap CMS, Ghost).

That's the general idea. You would typically have this integrated into your computing envrionment in some way, for example using exports, aliases and functions, and your .bashrc file, or you might have a custom app.

While templates enforce consistency, markdown provides a clean, flexible container with HTML pass-through, and frontmatter adds structured metadata. Together, they turn your local filesystem into a powerful, extensible system for managing content and code across any domain. The key take away is that by standardising on markdown and frontmatter and designing a sensible file structure, you can have a portable setup that you fully own and control, which you can easily work on with LLMs/AI agents.

I have written many articles over the years about why using git for content is worth considering, but now in the age of LLMs and AI, there are even more reasons to move to git powered content workflows. Here are some of the main ones:

• Commits as precise save points: Ditch messy file names like draft_v1_final_revised_2.docx for a clean history where every change has an explicit, readable reason attached to it.

• Everything is a file: Storing content as plain text or Markdown means you aren't locked into proprietary, closed-ecosystem databases. Your content remains fully portable, future-proof, and entirely yours.

• Pull Requests (PRs) as clean conceptual boundaries: Instead of editing everything live in one chaotic space, every piece of writing (a blog post, note, or resource) lives in its own isolated branch/PR. This gives you a high-level view of your project's evolution without drowning in micro-edits.

• Automated pipelines and syndication: Treating content as version-controlled files lets you hook up continuous integration (CI/CD) to automatically validate formatting, trigger static site builds, or syndicate RSS content across platforms.

• The Agentic Era & Ubiquitous AI: Content workflows are no longer just human-to-human. With AI and LLMs available everywhere, your Git repository acts as the ultimate workspace for human-agent collaboration—allowing autonomous tools to draft, review, lint, and refine your text seamlessly via standard PR workflows.

Another thing to consider is that fact that for content creation day to day you really only need 5% of git. You can completely skip advanced concepts like interactive rebasing, cherry-picking, submodules, or complex merge tools. You just don't need them. However they are there if you ever do for some reason need them, if you are doing something advanced, or working with programmers who do use them.

The point of this post isn't to be a tutorial on git, but just to give a sense for the terminology and the small subset of commands you actually need, here is a list of the most common commands you would be running:

• git status – See what files you've changed.

• git branch – List your local branches so you always know where you are.

• git checkout -b <branch> – Open a fresh drafting workspace.

• git add <file> & git commit -m "..." – Save a local snapshot.

• git log --oneline – View a clean, single-line history of your commit titles.

• git push – Back up your work to your remote host.

• git merge – Bring your finished draft into production.

And it's worth remembering that you can setup exports, aliases and functions in your shell configuration for many of these commands, so that you literally only need to type a few keystrokes to do each task.

Git branches are your risk-free drafting spaces. The main branch of a repo is production. It holds the live published version of your blog, docs, site, configuration files, or whatever text files your project consists of. Feature/draft branches are sandboxes to test bold structural changes, alternative introductions, controversial takes. If an idea fails, delete the branch with no impact on main. You can have multiple articles or edits in progress simultaneously without cluttering up your main workspace. Once you are sure the draft branch fits correctly, you safely merge it into the main branch.

For backup, collaboration and auto-publishing you can make use of remotes. With git you always have a full copy locally, but remotes serve as a full mirror. If your hardware fails, or you accidentally delete something important, your entire writing history remains safe. You also gain automated publishing capabilities, for example pushing your main branch to a remote can automatically trigger static site generators, to build and deploy your live site. You also get asynchronous review, editors and co-authors can review pull requests and leave line-by-line feedback using standard code review-tools.

The thing that really makes git powered content workflows feasible is that modern LLM/AI tools can be used to troubleshoot any git issues you run into. In the past running into a detached HEAD state or a merge conflict meant deciphering terminal errors or searching forum threads, but modern LLMs are trained on a ridiculous amount of scenarios. They have seen it all, and any hiccup is trivial to fix. Simply paste your command and the error output into ChatGPT or Claude and ask "How do I get back to a clean state without losing my text?". The AI is your instant Git coach. You can experiment freely knowing you have an on-demand assistant to guide you out of any state.

Git branches and remotes turn writing from a risky, file-juggling process into a structured, stress-free system. With a tiny command footprint and LLMs on standby to handle edge cases, while opening the door to automated pipelines and agentic collaboration. Treating your words like code gives you maximum control with minimal friction.

It‘s tempting to instinctively reach for databases, proprietary apps or complex SaaS tools when starting new projects, but it‘s worth remembering that there is an incredibly flexible set of tools baked right into the OS. What's more is that they have been tried and tested over many years. That's not to say that they should be used for everything, but they are a great foundation to start building, and often compliment other more complex tools. They are a great way to bootstrap your own custom computing environment, no matter the task.

The first thing might seem very obvious, but they are perhaps the most well known primitive in all of computing: files and folders. They are your agnostic storage layer. In fact on unix / linux operating systems, "everything is a file" is literally part of the entire philosophy. Flat files (markdown, plain text, etc) outlive platforms and apps. They are portable-human readable and naturally ready for AI/LLM tools without custom data pipelines. By designing a thoughtful naming hierarchy and using timestamped paths (e.g. content/posts/2026/2026-01-12-235959-title.md), your directory tree is your database. Standard filesystem tools handle sorting, filtering and indexing out of the box.

On the other hand exports, aliases and functions form your personal workspace engine, turning your terminal into a tailored environment for any task.

• Exports: Give you a way to set environment variables to hold values like the paths to often used directories, so your setup translates seamlessly across machines.

• Aliases: Compress daily repetitive commands into 2-to-3 letter muscle memory commands that you can trigger in an instant. Launch applications with pre-prepared options, navigate quickly across the file system, and a lot more.

• Functions: When aliases start getting too complex, switch to using functions, a way to add logic, accepting arguments, and chaining commands to automate workflows right inside your environment.

A new project is an evolutionary journey. The way to build great architectures is to evolve them out of real usage, real friction, actually using tools to achieve your goal, as opposed to guessing and building everything at once. You start with raw files and folders, add aliases for speed, write shell functions for multi-step tasks, and only build dedicated CLIs or servers when your workflow patterns solidify. Many of my projects started out as a collection of exports, aliases, and bash functions.

This might seem a bit complex, but remember with the help of LLMs, these days you can write functions and more complex custom scripts effortlessly.

Once you have your exports, aliases and functions you can easily add them to your .bashrc file so they are auto loaded when you boot the OS, ready in the background on every terminal you open. While I focus on linux systems, the same features are available on Windows via PowerShell profile scripts.

To give you a better idea of what is possible, take a look at my dotfiles.

Start simple, stay portable, and let your tools grow out of your actual needs.

I had a chance to check out the iPhone Duo earlier in a real life store. After reading a lot of reviews, I was thinking it was going to be some sort of massive brick phone from the 80s or something, but actually it was smaller than I had expected. I mean it is thicker than most phones for sure but each pane is actually kind of thin, it's just thick when its folded. It felt quite sturdy.

The outer screen is about big enough to do simple emailing and web browsing. I tried both Mail and Safari on the outer screen and it looked okay. It took me a little while to figure out the new gestures. Once I got the hang of swiping an app out of full screen mode, it was very usable.

Of course the big draw is the fully open screen, which is very impressive. It's basically a small iPad. Would be great for watching videos. I only had a few minutes to get a sense of the general shape, size and weight.

I didn't get a chance to have two apps open side by side, I couldn't figure out how to do that. That was a bit disappointing, because since I know it can run apps side by side, of course I am wondering if you can run a text editor on the left and a web browser on the right, and use it as a mobile web development machine.

I think if I was just a regular tech user I would probably really like it. As a web developer though, I can't help but wonder what a slightly bigger size would be like. The passport size seems like it might be a bit too small.

I currently have Galaxy A05s, and I am left wondering how cool it would be if the big screen, folded out to a massive double big screen. That would defo be able to run a text editor and a web browser side by side. The other thing, to be honest is that as slick as Apple products are, I am really quite happy with Android as an OS, especially when it comes to running a terminal using Termux.

Anyway, it's an interesting form factor, I was pleasantly surprised.

I just spent all morning searching through all my Gemini chat sessions for a particular conversation thread we had several weeks ago. I remembered that the later part of the thread had the useful information I wanted, where we went slightly off topic and discovered something really interesting.

The search features are kind of limited as far as I can see. It's basically just simple text string matching, with no obvious way to search using date ranges for example. The results do have a date associated with them, but individual threads don't have a created on timestamp when you are just browsing.

In the end I gave up and got on with the day. Much later I realised that perhaps I had had the conversation in ChatGPT, and sure enough when looked I found it pretty quickly. Seems to me we need better search functionality inside the chats but we also need a way to search across all the different vendor chat sessions all at once.

I think over the next few months we are going to start seeing a massive wave of new software releases. It's been a good number of months now that AI agents have been of a high enough quality that many software developers are using them extensively. While so far we have mostly seen vibe coded, interesting, but nevertheless hobby projects, what we are going to start seeing is devs who have been working on much larger projects start to release things.

I'm talking about software projects that would have previously taken large teams months or even years of effort. That can now be achieved by solo developers over a few focussed months. It's going to be really interesting to see as these projects start to surface. I might be one of such devs :)

There's a real potential for very niche products to start emerging. Great time to to be a developer and / or a tech enthusiast.

The gang stalkers were out in force again today, even if they were being more subtle. Part last night's harassment was an individual, who had clearly been waiting for me to arrive walked out in front of me, he was holding a very distinctive red bag. There were also several gangs on either side of the street at specific points making it difficult to cross. It was pretty clearly a setup, they wanted me to walk behind red bag bloke.

It was so obviously a setup too. Everything had been normal, and then when I got to the choke point, if you looked up the street you could see all the various little gangs on either side of the road going on for several hundred meters. I crossed the road anyway, took a diagonal line, and that's when one of the gangs got verbally abusive, several shouting No! at me loudly as I walked out of their trap. It was pretty dangerous as their shouting caused me to look the wrong way, and I very nearly got hit by passing traffic.

Well wouldn't you know it today in the local shop, where I often go for groceries, the girl at the counter started putting my things in a transparent unbranded bag (very unusual), but also didn't ask if I wanted a bag before doing so (very unusual). I politely said I no thank you for the bag, I always bring my own. She obviously got offended in some way (apparently), and started randomly saying No! and Bad! and laughing with here colleague. I said nothing, packed my bag with the things I bought, politely said thank you to them both, and departed.

Perhaps you think I am over reacting? Guess what happened next. On the way back, no less that 3 individuals, in 3 different locations, who were just waiting, loudly said No! to me as I passed. One was on a motorbike who dangerously pulled up directly in front of me. All these events are planned. They are all part of yet another intimidation campaign, carried out by just regular looking people of all shapes and sizes, all races were represented. What had I done to deserve such treatment? The only thing I can think of is it's writing this blog, because I've very much been keeping to myself lately.

People are worried about AI and super intelligence or whatever. I worry much more about people. Whatever they learn training these new AI models can, will and in my opinion clearly is being used by humans on other humans. It's horribly horribly ugly. I personnaly believe it's this sort of thing that causes societal decline, even though likely those doing it believe the opposite. I've seen it and experienced it in one way or another in many different countries, in 3 continents around the world, and it seems to me it's getting worse.

I'm just emerging from a bit of a nightmare related to higher level classes, hence this cautionary note. It‘s particularly relevant if you are coding with LLMs.

The crux of it is quite simple. I had a need to create some decorators, which is a way of dynamically adding new behaviors or responsibilities to an object or class without altering its underlying code. It is a quintessential example of composition over inheritance: instead of creating a rigid, deep subclass hierarchy to add a feature, you wrap the target with a decorator that intercepts or enhances its functionality. At it's core it's just a function that takes the class, method or property as input and wraps it with extra logic, and returns the enhanced version.

They are referred to as higher order function, or loosely as "higher-level" because they are functions that take other functions as arguments or return them. The annoying thing about higher-level functions is that they are tricky to reason about. Taken on their own, not so much, but when they are surrounded by a much bigger codebase, the level of complexity you have to hold in your head gets gnarly fast. But they can be very useful, and in some circumstances it's literally the only way of achieving what you want.

I have used decorators a lot before, in fact in nodejs you are using small versions of these all the time, but I hadn't had to use them to decorate classes before, and that is what the LLM I was working with suggested. As we were tackling a quite tricky thing, it made the case for using some class decorators. It made a lot of sense, and quite quickly we were off to the races. Of course I reviewed the code, but I didn't dig too much into the detail and I certainly didn't think about the longer term consequences.

As if often then case with software, as we continued to work on the feature, we discovered that the initial solution, and in fact the architecture it was embedded in, needed to change, and we set about doing that. This is where things started going off the rails, and at first I didn't notice. In my head it seemed that the higher order function solution was quite self contained, but as we re-architected the code, the LLM re-architected the higher order classes implementation, and in retrospect, it clearly got a bit confused, or just didn't think it through properly.

At a certain point I realised that the LLM had added several layers of indirection, which wasn't totally obvious because it was spread across several files in very different locations, and when I asked about these layers, it had very good arguments for them. They are acting as "runtime binding factories" was one that initially sounded like it could be a real thing that was needed. You have data at runtime that you need injecting into the class you are decorating, so of course you need a runtime binding factory. Duh. Yet somehow the more I asked about it, the more the explanations seemed contrived.

I eventually paused everything and dug into it myself, and painstakingly traced the code through and discovered all these horrific levels of totally unnecessary complexity, with very confusing function names, and to make it worse it had been importing various things and stuffing them inside closures at every level. A real tangled mess. Yet somehow it sort of worked, until you tested it properly, or refactored it slightly and it all fell apart.

I started by trying to rename all the function names to names that actually made sense. Often these ended up being ridiculously long names, which in itself was a sign things were not right. Anyway doing that enabled me to point out how unnecessary much of the cruft was, and soon enough we were able to drastically reduce the number of useless levels of complexity and unnecessary imports and closures.

All that said, the final solution is very neat, and actually not that complex. It's a little bit more complex than normal code, but not that much, and it's only in a very well understood place, and done in a repeatable way. The point is that if you are writing higher order functions with LLMs, it's worth slowing down and really make sure you understand the logic because it gets gnarly fast and the LLMs are unbelievably good at creating a giant knot out of everything and then telling you how great it is.

It‘s really terrible what‘s happening in France with all the school kids rioting. Protesting injustices isn't the issue, that should happen, but the tricky thing is that in this case the fact that they are tearing up the schools is literally making things worse for themselves. If the school system is already at breaking point, and by all accounts, with 45 kids in classes, it certainly sounds like it is, the last thing you want to do is make the situation even worse.

An interesting side note about language, I was looking up the translation of "self-defeating" in french. they have "contre-productif", but in my mind it lacks the "self" part, which is very important to get across the idea that you are hurting yourself. While they also have "auto-destructif", with "auto" from the Greek "autos", which means self, and I do remember it being used in this context, it‘s a strange one where I feel like somehow the modern use is somehow very linked to automatic, and so it‘s been sort of hijacked. To expresss this well you have to use a turn of phrase, like to shoot yourself in the foot ("Se tirer une balle dans le pied"), or to cut the branch you are sitting on ("Scier la branche sur laquelle on est assis").

Anyway while there will be some in the UK that will enjoy some sort of schadenfreude by seeing the french hurting themselves, it‘s a cautionary tale, because especially in a wider economic decline that we are in, and have been for years, this could very easily happen in the UK. It occurred to me that it might be worth getting ahead of this in some way. For universities you could make it into an excuse to have a cheeky pint with fellow students from another city, make it into a day trip, to forge connections, because if you ever do need to protest, you absolutely need it to be peaceful. And to do it right, you have to do it properly, tell authorities in advance, have a safe route etc, because there are those who will try to take it over because if it does lead to riots, they will benefit from you being in an even worse position later. This is the reality we live in, and that is only going to get worse the more along the decline road we get.

I'm not sure how you could extend this to schools, pints are no good for that, but it would be worth having some sort of forum, that doesn't in itself cause problems, because if we ever do get to that stage, where protests are needed, and they can be very powerful, it‘s perhaps the most important thing that it‘s Gandhi style sit downs rather than destroy the school and the neighborhood.

And of course while that's an important thing, equally important is to stop this infernal decline, something which the backs of napkins throughout history can attest to, is also very well suited to such forums.

I just mostly completed a massive refactor of the entire outer shell of my publishing server. A few days ago when I discovered it was necessary I was thinking to myself, oh no yet again Gemini has got me to a summit only to tell me that it all had to be completely redone. That has happened so many times.

It wasn't at all obvious how it could be achieved but the LLM came up withe a pretty awesome plan, though it did take me several hours to figure out what it was on about. Anyway long story short, what seemed completely impossible was actually very doable, as we had already laid the groundwork. So we were able to completely rewrite the entire outer shell, everything inside for the most part remained in the same place, but the outer shell was completely re-architected.

I'm still kind of amazed that it worked. And though I still have a few modules to convert to the new architecture, it's looking really really great.