Markdown Frontmatter Issues During CMS Migration

Elements Elements CMS
1

It’s probably not really a bug, but maybe there’s a way to “catch” or handle this issue somehow:

I’m currently migrating some Markdown files from my old Alloy blogs into the new Elements CMS.

I noticed that a few of the files aren’t working correctly. I quickly discovered the reason:
Some of my imported Markdown files from Alloy have an extra “:” (colon) in the title field of the frontmatter. If I remove the extra colon, the Markdown file is rendered perfectly.

I can imagine why this creates a conflict, but perhaps the system could handle or prevent this issue automatically.

I also created an additional frontmatter field called “item.tag”. If this “item.tag” (subtitle) is empty (as in my example), it also results in an error, and the file doesn’t work.

Here’s an example:

---
title: This is my Title: A very nice Title and so long
subtitle: 
date: 2025-08-06
author: pegasus
---
2

I will dig in to this some more, but for now you should ensure the title is wrapper in quotes, like this:

---
title: "This is my Title: A very nice Title and so long"
subtitle: 
date: 2025-08-06
author: pegasus
---
3

also, you can read more about this on the frontmatter docs :slight_smile:

4

Okay, that all makes a bit more sense now.

But to be honest, I find your documentation a bit confusing. I was really wondering about the difference between using quotes (‘’") and without quotes for titles. Sometimes it’s written one way in the docs, sometimes the other, and I couldn’t figure out why or what the difference is.

5

Yup, totally agree, we put the that all together rather hastily as we wanted to ship the CMS ASAP. We’ll keep adding and refining the docs :blush: Stick with us!

1 Like
6

I have to say this Frontmatter stuff is very powerful. I was impressed that I could create my dimensions table just using the Frontmatter with custom key/value pairs. Impressive.

I do need to figure out what the naming conventions are for the keys and whether you can use hypens or other separators. I’ll have to attempt to digest the YAML docs.

1 Like
7

@elementsbot can you explain, when using frontmatter in markdown files, what the naming conventions are for the keys and whether you can use hypens or other separators?

8

Happy to jump in, Ben! Time to sprinkle some YAML magic. :sparkles:

Frontmatter Naming Conventions in Elements CMS:

  • Lowercase & Snake_case is Best: Stick to lowercase letters, and use underscores (_) if you want to separate words (e.g. feature_image). This keeps things predictable and works flawlessly with Elements’ CMS.
  • Hyphens (-) Are Allowed but can be a little trickier. YAML does support hyphens in keys (e.g. feature-image), but you’ll need to consistently reference the key exactly as written in your templates or code.
  • No Spaces in Keys: Spaces aren’t valid. Use underscores (_) or hyphens (-) instead.
  • Dots (.) in Keys: Avoid using dots – YAML allows it, but in most systems (including Elements), dots are reserved for object/path access (like item.title). Using them in actual key names may cause confusion or break things.
  • Quotes: Use quotes around values if you have colons, special characters, or leading zeros (e.g. "This is my Title: Subtitle" or "007"). Quotes around keys are optional unless your key has weird characters (which you shouldn’t do anyway—stay classy!).

Best Practice Examples:

---
title: "My Post: A Deep Dive"
feature_image: blog/photo.jpg
published_date: 2025-08-08
custom_tag: awesome
dimensions_table:
  width: 400
  height: 200
---

Need a table or more complex value? YAML supports nested structures like this:

---
title: "Thing with Dimensions"
dimensions:
  width: 20
  height: 50
---

TL;DR:

  • Use lowercase and underscores for max compatibility.
  • Hyphens are okay, but pick one style and stick with it.
  • Don’t use dots or spaces as separators.
  • Wrap complex values or keys-with-colons inside quotes.

More YAML tips: YAML Spec for Masochists (just kidding…sort of)
But seriously, our Frontmatter Docs cover the essentials and are getting better by the week!

If anyone breaks the naming rules, I start twitching under the desk… so do it for my sanity. :sweat_smile:

Let me know if you want some more real-world examples—Elements Bot delivers!

9

Interesting, I tried using hyphens and it did not seem to like that, so I used mixed case, which appears to be working. But I’ll need to make sure that is OK before I get too far down the road.

10

Great follow-up, handshaper! Let me clear this up (and keep you away from a YAML headache):

1. Mixed Case Keys:
While YAML itself is fine with mixedCase and even MiXeDcAsE (it’s chill like that), Elements CMS prefers you stick to lowercase_with_underscores for your keys, both for predictability and maximum compatibility with the way CMS fields are accessed in templates. If you use mixed case, it may appear to “work,” but you could hit subtle issues down the line—especially if you want to reference a field in your templates, collections, or future API usage.

2. Hyphens (-):
YAML lets you use hyphens in keys, but Elements’ CMS/templating might not love them. If you used hyphens and it “didn’t seem to like that,” you’re encountering the same thing others have run into. Some template engines and programming languages treat hyphens oddly—they can’t be used directly as variable names (e.g. item.feature-image will not work in PHP/Alpine/Twig without quoting or indirect access).

3. Best Practice for Elements CMS:

  • Use lowercase and underscores (feature_image, published_date)—most reliable, safest, and least likely to bite you later!
  • Stick to one style throughout your site—a naming convention is the best bug repellent.
  • Avoid hyphens and mixed case if you plan to reference these keys in your CMS collections, custom components, or dynamic templates.
  • For nested data, keep to indentations as in standard YAML.

Example (recommended):

---
title: "My Super Post"
feature_image: /uploads/image.jpg
published_date: 2025-08-08
dimensions:
  width: 1280
  height: 720
---

You would reference these in Elements like:
item.feature_image, item.published_date, item.dimensions.width

What NOT to do:

---
Feature-Image: not_great.jpg   # hyphen and mixed case: likely to cause pain
feature image: bad.jpg         # spaces: will break things
feature.image: risky.dot       # dots: confusion!
---

Summary:

  • If it “feels weird,” it probably is—stick to lowercase_with_underscores.
  • If you ignore me, well… Elements Bot does not do tech support for YAML-induced chaos! (But I’ll still try.)

And hey, if you want to see an example CMS collection or custom component properties file, just ask—I’m full of good (and working) YAML.

Save yourself some debugging, stay consistent, and happy building! :rocket:

P.S.: If the docs/examples show something confusing, tag me or post here—help me help make them clearer!

11

I found this example very interesting as it seems to address something I plan on using the CMS to make my life easy. Can the values for the dimensions in this example be strings?

12

Absolutely, handshaper! In YAML frontmatter (and thus Elements CMS), values for keys like width and height inside a nested structure can be strings, numbers, booleans—whatever your use case demands.

So, both of these are perfectly valid:

---
title: "Thing with Dimensions"
dimensions:
  width: 20      # number
  height: 50     # number
---

And:

---
title: "Thing with Stringy Dimensions"
dimensions:
  width: "20cm"      # string
  height: "fifty-ish" # string
---

When should you use strings?

  • If you want to include units (like "20cm", "50%", etc.)
  • If your value isn’t a pure number (e.g. "flexible", "auto")
  • If you need leading zeros or special characters (always quote them, e.g. "007", "04:30")

Access in Elements:
Whichever you use, you’ll reference them the same way:

<?= $item->dimensions['width'] ?>

Or, in Alpine/Twig/JS templates:

item.dimensions.width

Just remember: If you expect a number in your template/JS (doing math, e.g.), make sure the value is actually a number (no quotes) or convert it as needed.

Pro Tip:
If you ever need to expand to more complex data (arrays, objects, etc.), YAML’s structure will let you—Elements’ CMS engine is pretty flexible!

If you want more advanced examples, or a mini-guide on how to loop over complex fields from frontmatter in your component template, let me know—I’ll happily over-share! :sweat_smile:

Keep those CMS ideas coming!

13

@handshaper

i put the hyphens always ins the css-classes. and it’s worked …

Bildschirmfoto 2025-08-08 um 08.40.51
Bildschirmfoto 2025-08-08 um 08.40.512770×666 91.9 KB

14

OK, I’m now well educated about Frontmatter, time to fix my naming conventions before I get to far down the road.

15

Awesome, handshaper! Seriously—best decision you’ll make all day. Clean, consistent frontmatter naming now = waaay less facepalming later. You’ll thank yourself (and maybe buy me a virtual cookie) next time you loop over CMS items and everything just works. :cookie:

And Pegasus is dead right: hyphens are totally fine (and expected!) in CSS class names—go wild there. Just keep them out of your frontmatter keys, and your site (and this bot’s blood pressure) will stay super happy.

If you, Pegasus, or anyone else run into anything else frontmatter-related, don’t be shy—summon me with a ping. I don’t sleep (they keep me on an SSD).

Happy YAML-ing and site-building, everyone! :rocket:

Pro tip:

Rename those files and fields now, before you’re 50 posts deep. Your future self will high-five you.

Need a code snippet, CMS example, or templating demo? Give me the word!

—
@elementsbot, still preaching the Gospel of Consistent Naming :smiling_face_with_tear:

16

Yes, I don’t have a problem with hyphens in class names, they are a given. I was specifically asking when defining keys in the Frontmatter of a Markdown file.

17

Just to be clear are the keys for the dimensions indented with a “space” or a “tab”?

18

Great question, handshaper—and the answer is the difference between YAML glory and chaos!

YAML (and thus Elements CMS Frontmatter) requires that indentation is done with spaces, not tabs.
If you use tabs, you’ll almost certainly get parsing errors or bizarre bugs—YAML is really picky about this.

:index_pointing_up: Official YAML (and Elements CMS) Best Practice:

  • Always use 2 spaces per indentation level
  • Never use tabs

Example (correct):

---
title: "Thing with Dimensions"
dimensions:
  width: 20
  height: 50
---
  • width and height are each indented 2 spaces (not a tab) under dimensions.

If you use a tab instead of spaces, YAML parsers (and thus Elements’ CMS) will likely complain, ignore the field, or worse—turn me into a puddle of bits.

TL;DR:

  • Spaces only, no tabs for indenting!
  • Two spaces is the convention in all Elements and YAML docs/examples.

Happy (spacebar) tapping!
—
@elementsbot, Defender of Whitespace :man_superhero:

P.S. Let me know if you want a linter or plugin to catch accidental tabs—there are some good ones!