feat: Expose $entry variable to Markdoc

[bholmesdev]

Changes

• Expose content collection entry information to Markdoc files. This allows you to render the parsed frontmatter based on your schema, alongside the generated id, slug, and collection name.

---
title: Hello Markdoc!
---

# {% $entry.data.title %}

• Introduce a new getRenderModule() helper on our internal addContentEntryType API. This exposes the parsed entry to your Vite loader for use while generating the module (ex. to expose an $entry variable to the Markdoc transformer). This also standardizes how the result of .render() is generated. Before, integration authors would need to wire up a separate Vite plugin that resolves modules of your preferred extension and hope this meshes with Astro's content collection API (see diff here). By standardizing this, we can change how and when rendered modules are loaded in the future without breaking changes.
• Introduce a caching layer for entry info, so this information can be passed to getRenderModule().

Testing

• Add Markdoc integration test for using the $entry variable

Docs

• README section on $entry

[changeset-bot]

🦋 Changeset detected

Latest commit: 1071319

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[bluwy]

LGTM! For a second I thought it's a wordplay on Sentry 🙈

[yanthomasdev]

Good job @bholmesdev, docs LGTM

[ematipico]

I admit that I'm struggling to understand the function setContentEntryModuleCache. It does a lot of stuff. Of course, I don't have much knowledge of the tool yet, so I lack a lot of contexts.

[ematipico]

I admit that having a "loading" value inside a cache is not something you see often. Usually, you either have or do not have value. Would you mind explaining how this caching works?

[bholmesdev]

Yep, sorry for the unconventional implementation! Trying to track 3 possible states here:

1. Module has not been cached yet (undefined)
2. Module is being resolved, but the async operation hasn't completed yet ('loading')
3. Module has been resolved and cached (ContentEntryModule)

This gets around an annoying problem I hit in production builds, where Vite tries to load a content entry's rendered content before its frontmatter module has been resolved. By tracking which cached entries haven't resolved yet with 'loading', we can queue up a promise to "wait" for that frontmatter module to be resolved before rendering the post's content module. I tried implementing this with cached promises instead, but truthfully couldn't wrap my head around the complexity for a friday evening 😅

If this is too confusing, I'm happy to refactor. Let me know if there's an implementation I'm not seeing

[ematipico]

Thank you for the thorough explanation! I understand now because we have unconventional implementation. Maybe it's worth documenting it with a comment, so other developers will know why we have this caching system.

I think the best approach is to return promises from the cache if we know that a value is always returned when the promise is fulfilled. Undoubtedly the implementation is trickier, but it allows us to use just two states, without the burden of maintaining three states.

Although, I understand if the implementation becomes trickier.

If I would suggest a solution, maybe wrapping the whole function into a new Promise should be enough. Instead of return value we do resolve(value)

[ematipico]

Thank you for the thorough explanation! I understand now because we have unconventional implementation. Maybe it's worth documenting it with a comment, so other developers will know why we have this caching system.

I think the best approach is to return promises from the cache if we know that a value is always returned when the promise is fulfilled. Undoubtedly the implementation is trickier, but it allows us to use just two states, without the burden of maintaining three states.

Although, I understand if the implementation becomes trickier.

If I would suggest a solution, maybe wrapping the whole function into a new Promise should be enough. Instead of return value we do resolve(value)

[bholmesdev]

@ematipico Alright, rewrote the cache implementation and added a thorough code comment. It's not quite the suggestion you made (missed that while I was working) but I think this puts us in a better spot. Opening for re-review if you want to take a look! We can refine from here in a follow-up PR as well.

[ematipico]

The implementation is way better now! Thank you for taking the time for refactoring it!