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 variables have 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.