Model the Data, Not the Interface

Sat, 08 Aug 2026 00:00:00 +0900

How a simple YAML data model let me add a client-facing CMS without touching the existing implementation.

The Story

A client asked for a profile page featuring his career timeline. Straightforward request. I built it, deployed it, and moved on.

Months later, he came back with a new request: he wanted to update the timeline himself—to add new positions and modify past entries.

Until then, I had been making those changes for him. Giving him direct access to the data wasn’t an option either: he was a non-technical user, and GitHub access was deliberately off the table.

At first glance, adding a content management interface sounded like a change that might ripple through the existing implementation.

It didn’t.

The reason went back to a small design decision I had made months earlier, before a CMS was even a consideration.

The Initial Design Choice: YAML Over Markdown

When I first built the profile page, I didn’t hard-code the timeline into HTML, but I didn’t put it in Markdown either. I started by asking what kind of content a career timeline actually is.

A career history isn’t really a document. It’s structured data: a collection of dates, each associated with one or more events. So I represented it that way:

# data/timeline.yml
entries:
  - date: 2020
    events:
      - Joined the neighborhood cat council
      - Took responsibility for afternoon naps
  - date: 2021
    events:
      - Became a boss cat
      - Led a team of 5 cats

I then rendered the data with Hugo:

<!-- layouts/shortcodes/timeline.html -->
<dl class="timeline">
{{ range .Site.Data.timeline.entries }}
    <div class="timeline-entry">
        <dt class="timeline-date">{{ .date }}</dt>
        <div class="timeline-events">
            {{ range .events }}
                <dd class="timeline-event">{{ . }}</dd>
            {{ end }}
        </div>
    </div>
{{ end }}
</dl>

This kept both the data structure and the implementation simple.

The career timeline rendered from the YAML data

Why YAML Instead of Markdown?

Many static-site workflows are Markdown-first, and for good reason. Markdown is excellent for prose: articles, documentation, and other document-shaped content. But not all content is document-shaped.

A career timeline is fundamentally a collection of structured records: dates with associated events. The same is often true of navigation menus, pricing tables, office locations, product specifications, and similar content.

Representing those structures as Markdown would mean making the data fit the document format rather than choosing a format that fits the data. For the timeline, YAML was the more natural representation.

I wasn’t thinking about CMS support at this point, nor was I trying to make the architecture extensible. I was simply representing the content in the form that best matched its nature.

That distinction became useful later.

The Requirement Change

Months later, the client wanted to manage his own career history. The new editing workflow had a few constraints:

It had to work for a non-technical user.
GitHub access was off the table.
Inputs needed validation: a year should be a number, and an entry should contain at least one event.
Changes had to be committed and deployed automatically.

The existing YAML files were already a perfectly good representation of the content. The problem wasn’t the data model; the problem was that the only interface for changing it was a text editor and Git.

So instead of replacing the existing content model, I added another interface to it.

The Solution: Add an Interface, Not a New Data Model

I used Decap CMS, a Git-based CMS that can map an editing UI onto files stored in a repository.

The configuration for the timeline looked roughly like this:

# static/admin/config.yml
- label: "Profile"
  name: "profile"
  files:
    - label: "Career History"
      name: "timeline_data"
      file: "data/timeline.yml"
      fields:
        - label: "Career entries"
          name: "entries"
          widget: "list"
          fields:
            - label: "Year"
              name: "date"
              widget: "number"
              value_type: "int"
              min: 1980
              max: 2050

            - label: "Events"
              name: "events"
              widget: "list"
              field:
                name: "event"
                widget: "string"
              min: 1

Decap CMS could now present the existing data as a form suitable for the client.

Resources

A minimal working example is available on GitHub, with a live demo deployed on Netlify.

The important part was what I didn’t change.

The YAML structure? ──Unchanged; The Hugo templates? ──Untouched; The site still rendered exactly the same way.

I had simply added a new way to edit the existing data.

Before (top) and after (bottom) adding a CMS: the existing data flow remains unchanged.s

No refactor, no breaking changes.

Why So Little Had to Change

What made this work was surprisingly simple: the editing side and the rendering side could depend on the same file-based data model.

File-based integration via a shared data contract

The Hugo templates depend on the structure of the YAML to render the timeline, while the Decap CMS configuration depends on the same structure to provide an editing interface. But the two sides don’t need to know about each other: Decap CMS doesn’t know how Hugo renders the timeline, and Hugo doesn’t know that Decap CMS exists.

They only agree on the shape of the data.

The YAML structure acts as a shared data contract between authoring and publishing. Adding another way to display the same data means writing another consumer of the model; adding another way to edit it means adding another authoring interface. Neither necessarily requires changing the underlying content model.

Of course, if the content itself changes—if a career entry suddenly needs locations, employers, categories, or relationships—the data model should change too. The point isn’t that the model never changes; it’s that adding an interface doesn’t inherently require it to change.

Model the Content for What It Is

What’s interesting to me is that none of this was planned. When I chose YAML, I wasn’t anticipating a CMS. There was no abstraction layer waiting for future requirements, no repository interface, and no elaborate content architecture.

I simply looked at the content and asked:

What is this thing?

The answer was structured data, so I represented it as structured data. That gave the later CMS integration a clean boundary almost for free.

This is different from trying to future-proof a system through speculative abstraction. I didn’t predict the future requirement; I represented the requirement I already had accurately enough that the future requirement fit naturally around it.

This applies beyond career timelines. A blog post or an article is usually document-shaped, making Markdown a natural fit. But a timeline is a collection of records, a navigation menu is a tree, and a pricing table is a collection of products, attributes, and prices. Different kinds of content have different natural structures.

So rather than starting with the tool—

How should I write this in Markdown?

—I find it more useful to start with the content:

What is this content, really?

The representation follows from there. Markdown is often ideal for document-shaped content. YAML, JSON, or another structured store may better represent structured content. Relational or highly dynamic data may belong in a database.

The specific format is secondary. What matters is whether the model reflects the structure of the thing being represented.

Takeaway

Adding CMS support to this site turned out to be surprisingly small—not because I had designed the system for a CMS or anticipated the requirement, and not because I had introduced abstractions to protect against future changes. I had simply modeled a career timeline as what it was: structured data.

When the client later needed an editing interface, Decap CMS could depend on that same model while Hugo continued rendering it exactly as before. The CMS became another interface to the data, rather than a replacement for the architecture.

That experience left me with a simple design heuristic:

Don’t model content around the tool that happens to consume it today. Model it around what the content actually is.

In this case, the flexibility followed naturally.

Cms on Rindrics Mumbles