docs: clarifying how dates work in frontmatter for content collections page

[jdwilkin4]

Preview link

https://deploy-preview-5234--astro-docs-2.netlify.app/en/guides/content-collections/#working-with-dates-in-the-frontmatter

Description (required)

This PR is responsible for adding a section in the content collection page on how dates work in the frontmatter

I am participating in hacktoberfest

Related issues & labels (optional)

• Closes clarify how dates work in frontmatter #4348
• Suggested label:

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	17c35f3
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/654175839c9f6a00088e945c
😎 Deploy Preview	https://deploy-preview-5234--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[sarah11918]

Thanks for grabbing another issue, @jdwilkin4 !

I think this could be even more helpful if we add how to then use the date (that's always the tricky part for me, because if you then try to render frontmatter.post.date you get the entire UTC string, and most people want to actually choose how to format their date.

Would you be willing to add another code snippet and explain that once you have your YAML date, you may wish to format it as a string and then you can either simply truncate the long string, or format something like this in your template?

// Renders only YYYY-MM-DD from the full UTC timestamp
 <p>{frontmatter.pubDate.toString().slice(0,10)}</p>

for more control over formatting

<h4>
	{post.data.pubDate.toLocaleDateString('en-us', {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
	})}
</h4>

and maybe mention that you can find an example of doing the above in a separate <FormattedTime /> component in the official Astro blog template because that might be yucky to throw directly in your template like that lol

https://github.com/withastro/astro/blob/latest/examples/blog/src/components/FormattedDate.astro

[Princesseuh]

This date format is not specific to content collections, it's a YAML thing so I assume this can also have effects outside of CC

[sarah11918]

Yes, it is the YAML spec, though I think it's maybe particularly a content collections issue because Zod requires this format if you want to use z.date() it has to be ISO8601. And I think people's first instinct would be, "It's a date, so I should use z.date().

In plain Markdown outside of collections, it's not checking that date is actually a date, so you could presumably put a string directly there in whatever format you like or use some functions to convert? So this content is probably useful to have for more than just collections, but I think it's probably most helpful to get it into collections to start since they're going to be forced into this here. Then, we can revisit/refactor!

[Princesseuh]

Yes, it is the YAML spec, though I think it's maybe particularly a content collections issue because Zod requires this format if you want to use z.date() it has to be ISO8601. And I think people's first instinct would be, "It's a date, so I should use z.date().

In plain Markdown outside of collections, it's not checking that date is actually a date, so you could presumably put a string directly there in whatever format you like or use some functions to convert? So this content is probably useful to have for more than just collections, but I think it's probably most helpful to get it into collections to start since they're going to be forced into this here. Then, we can revisit/refactor!

Zod does not require a ISO8601 date, it accepts a JavaScript Date object, not a string. YAML (and so js-yaml, the library Astro uses to parse the frontmatter) however requires a ISO8601 date to consider a string to be a date and convert it into a Date object, otherwise it stays a string. If you were to use z.coerce.date() instead of z.date(), which is what our blog template does, it would work no matter the format, because it'd work directly on the string

The nuance is important because in a normal Markdown file, if you put a ISO date in the frontmatter, you'd get a Date object and not a string

[sarah11918]

Ah thanks for that! I was reading Zod docs and they said they require ISO8601, but I suppose they meant for that to be user-facing, what you'd put in your YAML (though internally they are using a date object). I noticed that coerce.date was recently (according to them) added, but that's a bit much for us to get into in our docks to let people enter different date formats - we're really not trying to explain how Zod works per se, nor general JavaScript dates for that matter. (But, if it's affecting people using content collections, better to give an example of something that will work. Those who know more can do their own thing.)

So, I see a couple of options going forward:

1. We publish a section like this here for now because it's helpful to content collections users firstly (and, we're pushing people to use content collections, and the people who have all brought up having trouble with dates have been using content collections)
2. We make this a standalone recipe for working with dates in your Astro blog, and we refocus it on YAML, mention using it in file-based routing Markdown files AND how it works in collections, and then we have the luxury of adding some nuance. We can then link to it from here, if we want, or it's discoverable when people search for how to do dates.
3. (Maybe in conjunction with number 2) We add simply a line to this comprehensive code sample here https://deploy-preview-5234--astro-docs-2.netlify.app/en/guides/content-collections/#defining-datatypes-with-zod that shows the date format, to nudge people towards using it in their YAML. Then, at least they've seen that format, and we don't have to explicitly say one way or the other whether that's a required format, or the only way to do it. e.g.

// In frontmatter, dates written without quotes around them are interpreted as Date objects
publishDate: z.date(),
// e.g. 2022-07-08
// You can also transform a date string (e.g. "2022-07-08") to a Date object
// publishDate: z.string().transform((str) => new Date(str)),

Not gonna lie, already that section looks like it's trying to do too much, so I do think some extra date advice somewhere is necessary!

So @jdwilkin4 I'll let you decide if you think you want to expand this into a full "recipe" format, guiding people how to thing about doing dates, or just continue the section here! The most important part is getting content written and published, and then we can always move it around or decide later!

[jdwilkin4]

HI @sarah11918 !

We publish a section like this here for now because it's helpful to content collections users firstly (and, we're pushing people to use content collections, and the people who have all brought up having trouble with dates have been using content collections)

I like going with this option 👍

I will go ahead and add those additional code examples you mentioned in your first comment here

#5234 (comment)

[jdwilkin4]

@sarah11918

I pushed an update for adding an additional example

and maybe mention that you can find an example of doing the above in a separate component in the official Astro blog template

I wasn't able to find the Formatted date component in the blog tutorial here
https://docs.astro.build/en/tutorial/0-introduction/

Should I just use the link straight to the github example here?
https://github.com/withastro/astro/blob/latest/examples/blog/src/components/FormattedDate.astro

[sarah11918]

@jdwilkin4 Yes! It's not in the blog tutorial, it's in the blog template from Astro.new. You found it! That's the right one!

[sarah11918]

Thanks @jdwilkin4 for being so responsive! What do you think of my suggestions? Just made a few minor changes, and I think we can get this in for 🎃 !

[sarah11918]

I think you're going to be Astro Docs' final 🎃 merge of the year!! Thank you for your service, and plant that tree! 🌳