Building The Vibe-Coder's Dictionary

The Problem Nobody Talks About

Here’s something I noticed while writing the first blog post on this site. I kept stopping to explain things. Every few paragraphs, there was a word or phrase that would make perfect sense to a developer but would lose everyone else.

Repository. Context window. Static site. Build time. Selective hydration.

I was writing for non-technical readers, people like me six months ago, and I kept hitting the same wall. Either I explain every term inline and the post becomes a textbook, or I skip the explanations and lose the audience I actually want to reach.

Neither option worked. So I built a third one.

What if Technical Terms Had Their Own Pages?

The idea was simple. What if every technical term on this site had its own page? A short, plain-language explanation written for someone who has never opened a terminal. Not a Wikipedia article. Not a Stack Overflow answer. Just enough context to keep you moving.

That’s The Vibe-Coder’s Dictionary.

It’s a growing collection of terms, each with its own page at /glossary/[term]. Words like Git, framework, deploy, component, and API.

Every definition follows the same structure: a one-line summary, a plain-language explanation (usually with an analogy), why the term matters in practice, and how it’s actually used on this site. Related terms link to each other, so you can follow threads naturally. And for tools like Astro or Claude Code, each glossary page includes a link to try the tool yourself.

The Workflow That Makes It Happen

Here’s the part I want to be honest about, because it’s the most valuable thing I’ve learned.

I’m not sitting here manually combing through blog posts and hand-picking which terms need glossary entries. That would take hours and I’d miss things. Instead, the system does it.

The way Claude Code works on this project, the instructions baked into PLAN.md and CLAUDE.md tell it to automatically identify technical terms as we write. When I’m drafting a blog post with Claude Code, it flags jargon as it appears, links terms to their glossary pages, and identifies which terms don’t have entries yet. Then we create those entries together in the same session.

The blog post gets written. The terms get linked. The missing glossary entries get created. It’s one workflow, not three separate tasks.

This is the real value of having a persistent plan file and operating instructions. Claude Code doesn’t just build features; it follows content conventions that compound over time. Every blog post automatically strengthens the Dictionary. Every new term becomes a potential search engine entry point. The system builds on itself.

How It Actually Works Under the Hood

The Dictionary is built on Astro’s content collections system. Each term is a Markdown file with structured frontmatter (the metadata at the top of the file that tells the system what the term is, how to categorize it, and what it relates to). Claude Code and I defined the schema, built the page templates, and seeded the initial terms in a single session.

The glossary index at /glossary pulls every term from the collection and renders them as a searchable, alphabetized list. Search is instant because it runs entirely in the browser, no server needed. Each term links to its own page with a unique URL, which means search engines can index every single definition independently.

That last part matters more than it sounds. Each glossary page is a potential entry point. Someone searching “what is a context window in AI” could land directly on that page, discover the site, and explore from there. Multiply that by dozens of terms, and you have a content engine that grows with every blog post.

The Self-Referential Part

Here’s where it gets interesting. The Dictionary itself demonstrates several of the concepts it defines.

The glossary is a content collection, and there’s a glossary entry explaining what a content collection is. The individual term pages use structured data for SEO, and there’s a term explaining structured data. The search on the index page is a React component running inside an otherwise static page, which is exactly what selective hydration means.

This is the meta-site principle in action. Every feature is simultaneously content for the reader, a demonstration of a technique, and a doorway to learning how it was built. The Dictionary doesn’t just explain the tools. It is the tools, running in front of you.

How It Connects to Everything Else

The Dictionary isn’t a standalone feature. It’s woven into the site.

Blog posts link technical terms to their glossary pages on first mention (you’ve probably noticed the links throughout this post). Even tool names like Vercel or GitHub link to the Dictionary first, where they get defined, and then the glossary page links out to the tool’s actual website. This means every external link on the site passes through a layer of context. Readers never get sent somewhere without understanding what they’re clicking on.

The DictionaryTeaser on the homepage pulls real terms from the collection, so it’s always up to date. Each term page links to related terms, creating a web of internal connections that readers can follow and search engines reward.

As new blog posts get written, new terms get added. The glossary grows organically with the content rather than as a separate maintenance task. Write a post, the terms get flagged, the definitions get created. That’s the workflow.

What I Learned

The hardest part wasn’t the code. It was writing definitions that are genuinely useful without being condescending. There’s a tone challenge in explaining technical concepts to smart people who just haven’t encountered these words before. You have to respect the reader’s intelligence while acknowledging the vocabulary gap.

There is something biblical about this work, even if it does not look like it on the surface. Genesis 2:19 says God brought the animals to Adam “to see what he would call them.” Naming things is one of the first tasks God gave to humanity. Defining terms clearly, giving people the language to understand what they are looking at, is not just a content strategy. It is a small act of stewardship. When you name something well, you give someone else the ability to think about it clearly. That matters.

The other thing I learned is that content architecture is a real skill. Deciding what constitutes a “term,” how terms relate to each other, what level of detail belongs on a glossary page versus in a blog post: these are editorial decisions, not technical ones. The code is straightforward. The content strategy is where the thinking happens.

But the biggest lesson? Build the system, not the content. Once the glossary infrastructure was in place and the conventions were baked into Claude Code’s operating instructions, new terms practically write themselves. That’s the difference between a one-time project and a compounding asset.

What’s Next for the Dictionary

The first blog post alone references over 30 terms, and more get added with every new post. The next feature is hover tooltips. When you see a linked term in a blog post, hovering over it will show the brief definition right there, with a “Learn more” link to the full page. That keeps readers in flow instead of forcing them to click away.

Eventually, the Dictionary could become a standalone resource. A free e-book. A reference guide for anyone trying to understand the technical landscape without a computer science degree.

But for now, it does exactly what I needed: it turns jargon into context, one term at a time. And because the system is designed to grow with every blog post, it’ll keep getting more useful without extra effort.

The best reference material does not just define words. It closes the gap between someone who understands and someone who almost does. That gap is where most people give up. A glossary that meets them there is worth more than another tutorial.

The tools that built this glossary are impressive. But they are tools. The impulse behind it, wanting to make knowledge accessible so that more people can build, comes from somewhere deeper. “Freely you have received, freely give” (Matthew 10:8). The Dictionary is one small way of living that out.

Reach out if you’re building something similar or want to talk about content strategy for technical audiences.

Explore the full glossary at The Vibe-Coder’s Dictionary, or check out how this site was built from zero.