Modern Websites, Managed Simply

I build a lot of websites.

Most of them run on GitHub Pages with Jekyll.

People assume the reason is that it’s free, or fast, or that I just like the command line. Those are true, but they’re not the reason.

The reason is that the content lives in files, and the way I change the site is by opening an issue and assigning it to an agent.

That’s the whole pitch. Let me unpack both halves.

---

Half one: the data lives in files

On most sites, your content lives in a database you can’t see.

You log into an admin panel. You edit a field. You click save. Somewhere, a row changes.

You don’t own that change in any way you can hold. You can’t diff it. You can’t see who made it, or why, or what it looked like before — not without a plugin, a backup, and a good afternoon.

On the sites I build, the content is a file.

The projects on this very site are a single file: _data/projects.json. Every project — its name, its description, its screenshot, whether it shows on the homepage — is one entry in that file. Add a project by adding an entry. Reorder them by changing a date. There is no “projects” screen to log into.

Blog posts are files too. This post is a Markdown file with a few lines of front matter at the top. The words you’re reading are text in a file in a folder called _posts.

This sounds like a downgrade. It’s the opposite.

When content is a file, you get things the database never gave you for free:

• History. Every change is a commit. Who, what, when, and why — permanently, with a message attached.
• Diffs. You can see exactly what changed between two versions. One line, or one hundred.
• Review. A change can be proposed, read, and approved before it goes live.
• Portability. The site is a folder. It’s not trapped inside anyone’s platform. You can move it, back it up, or read it in a plain text editor twenty years from now.

The database gave you a form to fill out. The file gives you the actual thing, and the whole record of how it got that way.

This is also a stewardship argument, not just a convenience one. A website is a public record of an organization. Content you can hold, diff, and carry forward is content you can steward. Content locked in someone’s database is content you’re renting.

---

Half two: the update flow is an issue assigned to an agent

Here’s the part that’s changed recently.

For years, the tradeoff was real: files are better to own, but a content management system is easier to edit. Your client doesn’t want to learn Markdown. They don’t want to touch a repository. They want to say “change the hours on the contact page” and have it happen.

So you either taught them the files, or you built them an admin panel, or you became the admin panel yourself.

That tradeoff is mostly gone now.

The update flow I use looks like this:

1. Someone opens an issue. Plain language. “Add the new landscaping project, here’s a screenshot and a paragraph.”
2. The issue is assigned to an agent.
3. The agent makes the change — edits the file, resizes the image, opens a pull request.
4. I read the change. It’s a diff. I can see exactly what it did.
5. I approve it, and it goes live.

The person requesting the change never touches a file. They describe what they want, the way they’d describe it to a person. The change still lands as a reviewable commit in a file I own.

You get the accessibility of “just tell someone what you want” and the integrity of a version-controlled file. The thing that used to force the tradeoff — a human translating requests into edits — is now something an agent does, under review.

The issue is the request. The pull request is the answer. The diff is the receipt.

Nobody logs into a dashboard. Nobody learns a proprietary editor. And nothing changes on the live site without a record of who asked and what got done.

---

A note on “WYSIWYG,” because the word gets misused

People reach for “WYSIWYG” to describe editing in something like WordPress.

It’s the wrong word.

WordPress is a content management system. You’re filling out fields in an admin panel, and a theme decides how those fields get rendered somewhere else. What you’re looking at while you type is not what the visitor sees. It’s a form.

WYSIWYG meant something specific, and it was real. Dreamweaver. HotDog Pro. You laid out the actual page — dragged the actual elements, saw the actual result — and the file underneath was the thing you were looking at. What you saw was what you got, because you were editing the got.

A CMS admin panel isn’t that. It’s a data-entry screen with a preview button.

I’m not nostalgic for the old editors. They made a mess of the underlying HTML, and they didn’t scale to sites that are really programs. But it’s worth being honest about the words. Most “visual” website editing today is form-filling against a database, dressed up to feel direct.

The files-plus-issues approach is more direct than any of it — not because it looks like the page while you type, but because the thing you change is the thing that ships.

---

When this is the right call, and when it isn’t

I’m not going to pretend this fits everyone.

It’s a strong fit when:

• The site is mostly content that changes occasionally — a business, a portfolio, a civic organization, documentation.
• You want to own the content outright and keep a real history of it.
• The people requesting changes are happy to describe what they want and let someone else — or something else — make the edit.

It’s a weaker fit when:

• You need constant, self-service editing by many non-technical people at once.
• The site is really an application with logins, user accounts, and data written by visitors.
• You genuinely need a live visual editor and can accept the platform lock-in that comes with it.

For most small businesses and civic organizations, though, the first list is the whole job.

The site is content. The content should be files. The changes should be requests you can read and receipts you can keep.

That’s how I run websites. It’s cheaper and faster, sure. But mostly it means the organization owns its own words — and can always see how they got there.