Why JSON-Driven Content Beats Hardcoded Templates

The Habit We All Have

Let me describe a scene. You’re building a landing page. You open your hero component. You write:

<h1>Build Better Products Faster</h1>
<p>Our platform helps teams ship more, stress less, and sleep better.</p>

It’s good copy. It works. You ship it.

Three weeks later, marketing wants to change the headline. Not the whole page — just that one line. It’s a five-word change. Easy, right?

You open the component. You find the line. You change it. You commit. You push. You wait for deploy. Marketing looks at it and says, “actually, can we try three options?”

You do it. Three times. And each time, you’re the only person who can make the change, because the text lives inside a component that only a developer can safely edit.

This is how most sites work. It’s also completely unnecessary.

What JSON-Driven Actually Means

JSON-driven content means the text, images, and links that appear on your site live in data files, not in your components.

Your component becomes a template. It knows how to render content, but it doesn’t know what the content is.

Here’s the same hero, JSON-driven:

{
  "title": "Build Better Products Faster",
  "description": "Our platform helps teams ship more, stress less, and sleep better.",
  "button": "Get Started",
  "button_link": "/signup"
}

And the component:

---
import Data from '../data/home.json';
---
<h1>{Data.title}</h1>
<p>{Data.description}</p>
<a href={Data.button_link}>{Data.button}</a>

Same output. But now the content lives somewhere else — somewhere a non-developer can safely edit.

Why This Matters

Non-Developers Can Make Changes

This is the biggest one. Marketing can update the headline. Product can change the pricing copy. Support can fix a typo in a feature description. Nobody has to wait for a developer, and no one has to learn a framework to make a text change.

You know what makes developers happy? Not being interrupted for text changes.

Content Becomes Portable

That JSON file can be used anywhere. The same home.json can power the landing page, a marketing email, an API response, or a mobile app — if you ever build one.

When the content lives inside a component, it’s locked to that component. When it lives in a data file, it’s content.

Translation Becomes Trivial

Want to add a second language? Duplicate the JSON, translate the values, swap based on locale. No source code changes. No branching logic in components. No duplicated markup.

Without JSON, you’d have to either duplicate the components or add conditionals everywhere.

Testing Is Easier

Want to test what the page looks like with a really long headline? Change the JSON. Want to see it with a shorter one? Change the JSON. No component edits, no risk of accidentally committing test content.

Designers and Content People Can Iterate

A designer can propose new copy. A content strategist can A/B test headlines. A translator can work on one language without touching another.

The content isn’t held hostage by code.

The Objection: “But Isn’t This More Files?”

Yes. Technically. You now have a JSON file for what used to be inline text.

But let’s count the files properly.

Hardcoded approach:

• 1 component with text inside
• Every text change requires editing that component
• Every language requires duplicating the component
• Every content update risks breaking the layout

JSON-driven approach:

• 1 component (doesn’t change)
• 1 JSON file (gets edited for content)
• Every language is a new JSON file
• Content updates are isolated from code

You’re adding one file and removing an entire class of problems.

Real-World Scenarios

Scenario 1 — The pricing page that changes quarterly. With hardcoded content, every pricing change means a code deploy. With JSON, it’s a file edit. Multiply that by every pricing tier, every feature, every FAQ. Now it’s a weekly task instead of a quarterly project.

Scenario 2 — The navigation menu that gets reorganized. Somebody decides “Pricing” should move before “Blog.” With hardcoded nav, you edit HTML, redeploy. With JSON, you edit an array. Save. Done. This might happen once a month or once a quarter, but it always happens.

Scenario 3 — The blog that needs tags and categories. Every blog post has frontmatter (which is JSON, effectively). The blog index reads that frontmatter to build tag pages, category pages, and the RSS feed. None of that would be possible if blog posts were plain HTML.

Scenario 4 — The landing page that gets A/B tested. You want to test two versions of the hero. With hardcoded content, you need two components or a conditional. With JSON, you have two files and swap based on a cookie or query param.

The Structure That Makes It Work

In Astro Docus, the JSON files live in src/data/. They’re organized by purpose:

src/data/
├── home.json               → landing page content
├── configuration/          → navbar, footer, blog metadata
├── index_page/             → card grids for docs landing pages
├── plan/                   → plan page content
└── pricing/                → pricing tiers

Each file is named for what it feeds. If you want to change the homepage, you open home.json. If you want to change the navbar, you open configuration/home/homepage.json. There’s no ambiguity.

The components don’t care. They just import the data and render it.

When Hardcoding Is Actually Fine

I’m not going to pretend JSON is always right. There are cases where hardcoding is genuinely better:

Throwaway prototypes. If you’re building a demo that’ll be thrown away in a week, don’t set up a data structure.

Highly dynamic content. If the text depends on runtime state (user name, time of day, etc.), inline code is often simpler.

One-off pages with no reusability. A legal page that will never be reused doesn’t need externalized data.

Content that lives inside a loop of other data. Sometimes the text is the identifier and shouldn’t be pulled out.

But for the pages most sites have — home, pricing, contact, about, blog list — JSON-driven is almost always the right call.

How to Start

The migration path is simple:

1. Pick one page. The homepage is a good start.
2. Identify the content — headings, paragraphs, buttons, images.
3. Move it to a JSON file in src/data/.
4. Import the JSON in the component.
5. Replace the hardcoded strings with {Data.something} references.

You’ll be done in an hour. And you’ll never want to hardcode content again.

Actually, that’s not true. You’ll hardcode a headline at 2 AM because you’re tired and it’s one line. Then you’ll regret it a week later.

We all do.

The Deeper Point

JSON-driven content isn’t just a technical pattern. It’s a way of thinking.

It’s the recognition that content is data, not code. That a headline is a value that can be changed, translated, tested, or handed off — not a string permanently welded into a component.

Once you see content that way, it’s hard to un-see it. You start noticing every hardcoded string. You start thinking about who might want to change it, and whether they can.

The answer, when content is in components, is usually “no one but a developer.” The answer, when content is in JSON, is “anyone with the file open.”

That’s a huge difference. And it costs almost nothing to get there.

Astro Docus uses JSON-driven content throughout — the landing page, navbar, footer, pricing tiers, blog metadata, and card grids all live in data files. If you want to start with this pattern already wired up, check it out on Gumroad.

Share This Article