Naming conventions that work: Simplifying your content repository

We’ve all been there: wading through a list of nearly identical “Hero” components, wasting 10 minutes just to find the right one. 

When content items are poorly named—or worse, all named the same—it turns even simple tasks into frustrating scavenger hunts. You waste time, lose focus, and start wondering if it’d be faster to just recreate the thing from scratch.

That’s a clear sign your content repository is missing one critical ingredient: content discoverability.

Clear, consistent naming helps your team find, reuse, and manage content efficiently—especially in a headless content management system (CMS), where linked items and reusable components are the norm. In this post, we’ll break down naming strategies that actually work, from linked content items to assets.

Why you should design naming conventions for your project

Your CMS can store thousands of content items, but if they’re all called “Article,” “CTA,” or “Copy Block,” then good luck finding what you need.

Good naming conventions:

• Make items easy to find using navigation or search
• Help editors and developers understand content at a glance
• Encourage reuse over duplication
• Scale with your content operations

Naming linked items: Be clear and contextual

In headless content models, each content item is often made of multiple linked items: hero parts, descriptions, calls to action, testimonials, and so on.

The issue? Most CMSs list these items by name—and if 100 items are just called “Hero,” you end up clicking into each one just to find out what it is.

Instead, use a structured naming format like:

[Content type] – [Title and/or context]

Examples

• Hero – How to create better content SEO LP
• CTA – Newsletter sign-up
• Testimonial – Eddie Munson Hawkins success story
• FAQ – What is a headless CMS?

This makes your repository more scannable, especially when you’re linking existing items. It also prevents future confusion when someone sees “Hero – How to create better Content SEO LP” vs. “Hero – SEO Landing Page.”

What’s great for me as an editor is that a CMS like Kontent.ai lets you filter by content type when you’re searching inside a project that has thousands and thousands of content items:

Filters are essential for editors working on large projects—they’re a daily tool that makes finding the right content faster and easier. But once you’re inside a content item filled with linked content items (which might link to even more items), filters won’t help you there.

That’s when a good naming convention really shines. Take this example: a CTA button inside a hero section, both linked to The Total Economic Impact landing page. Thanks to clear, descriptive naming, we can immediately see what each item is and how it fits into the larger structure—without opening them one by one.

Asset naming: Make files instantly recognizable

Image names like IMG_9384.jpg or screenshot2022-03-23-1449.png are a common trap. They’re meaningless when you need to search, filter, or even just understand what the file is.

You wouldn’t call a downloadable ebook “Document 1”—so why do it with images?

Use a descriptive, consistent format

[type]-[subject]-[context].jpg


Examples

• hero-how-to-create-better-content.jpg
• icon-arrow-right.svg
• banner-content-modeling-webinar.png
• thumbnail-tim-rodie-quote.png

Tips

• Use dashes, not spaces or underscores
• Stick to lowercase for clean URLs
• Include content type, subject, and optionally version or language
• Avoid unnecessary timestamps

This pays off for SEO (image alt text and file names matter), accessibility, and future-proofing your content for reuse across channels.

I can’t overstate how important clear, descriptive image naming is for search performance. Properly named images actually boost SEO by helping search engines understand page context better. Instead of generic filenames like ‘IMG_1234.jpg,’ use descriptive names that include keywords relevant to the content.

Roxana Pirlogea

Head of Demand Generation, Kontent.ai

This principle doesn’t just apply to images—it’s just as important for PDFs, videos, and any other assets uploaded to your CMS. Files like final-presentation-v2.pdf or meeting-notes-2024.mp4 quickly become confusing in a growing library. Naming assets with a clear, descriptive format makes them easier to organize, search, and reuse—especially when teams grow or when assets are needed to be shared across multiple channels. Imagine trying to find the right whitepaper or promotional video months later; document-final-final2.pdf won’t help. Instead, use names like ebook-hipaa-content-strategy.pdf or video-cms-overview-2025.mp4.

Reusability vs. specificity

The more specific an item is, the longer its name will likely be. And that’s a good thing: it signals to others that the item is context-specific and shouldn’t be reused elsewhere.

Think in tiers:

Avoid the temptation to call items “Mark’s blog post” or “CTA final.” Be specific enough that someone else could understand what the item is without opening it.

Tools and tips for content teams

• Create a naming conventions guide or cheatsheet for your editors
• Schedule quarterly cleanups to rename old items for clarity
• Use consistent patterns for prefixes: Hero, CTA, Video, Quote, etc.
• Add page or content context: – Homepage, – Blog Post XYZ
• Give images real names, not auto-generated ones
• Avoid duplicates like “Copy of Demo CTA” or vague labels like “HR page”
• Searchability > creativity when it comes to naming

Final thought

A messy content repository chips away at team productivity and sanity. Editors get frustrated hunting for the right content item. Multiply that across teams and projects, and you’ve got a real operational problem.

But you can start with simple, consistent naming conventions that reflect how your team works. Build habits. Set expectations. Use names that make sense today—and six months from now.

It's a small discipline that leads to a big payoff: faster collaboration, fewer errors, and content that’s easier to scale and reuse. Your future self (and your whole team) will thank you.