Excerpts (@islands/excerpt) aren't reliably extracted during dev

[nixyxo]

• [x] I have read the [troubleshooting section] before opening an issue.
• [x] I have tried upgrading iles and vite.

Description 📖

• On a fresh dev instance, with only modules: ['@islands/excerpt'] added to iles config (and npm installed).
• On first run, excerpt is only added to the first content item (see screenshot).
• After a change to a source file, triggering HMR, any excerpts that were added disappear.
• On stopping and restarting dev instance, excerpt is not added to any content items.

All content appears to be excerpted as expected on running npm run build then npm run preview.

Aside: I think I once saw item.excerpt was set and item.meta.excerpt was not set, but I could not reproduce that.

Reproduction 🐞

https://github.com/nixyxo/iles-excerpt-test

Dependencies Info

``` iles v0.7.38 vite v2.9.10 ``` ``` iles-app@0.0.0 /Users/nx/iles-excerpt-test/ ├── @islands/excerpt@0.1.3 ├── iles@0.7.38 ├── typescript@4.7.3 └── vue-tsc@0.29.8 ```

Screenshots 📷

[ElMassimo]

Hi nixyxo! Thanks for providing a reproduction!

The recommended approach to use an excerpt, is to render the componentin excerpt mode.

In your example:

<component :is="item" excerpt/>

---

@islands/excerpt adds a text excerpt to vfile.data, which is then injected in each page module within meta.

Since the purpose of useDocuments is to be able to obtain a reference to a potentially very large collection, forcing the parse of all files would slow down development. As a result, there's no guarantee that a page component will have been parsed before used by useDocuments is processed.

The behavior in this bug report is likely caused by a race condition, depending on when useDocuments is processed, each page will or won't have the metadata obtained by @islands/mdx when doing a full parse of the file.

You could also use import.meta.globEager to import the page components directly if you prefer, as a direct import will guarantee that the file has been parsed.

This should be in the documentation, keeping this issue opened as a reminder to add a warning tip in the Documents section, so that users don't rely on meta.excerpt being available in each document.

[ElMassimo]

This is documented in the @islands/excerpt usage instructions.

[nixyxo]

Thank you for the clarification.

I understand and agree with the logic around avoiding useDocuments needing to parse all markdown files in a large collection up front during dev.

I am able to use the excerpt prop on the component like in your example. I think that solves my use case.

I do think the docs around excepts could be clearer about this. E.g. sets meta.excerpt is not always true as you noted and I don't think the followup code samples were clear enough (at least to me) around why it works with usePage() and won't work with useDocuments() unless you use the component instance.

I'll think around if there are any docs edits that would have helped me get the concept better and not trip on expecting meta.excerpt to be set. I'll propose something if I find a good edit.

~ ~ ~

Lastly, thanks for making this great tool, overall I've found it to be very friendly and aligned to what I wanted out of a static site generator; I particularly like using Vue template syntax for everything.

[ElMassimo]

Thanks! Improvements to the docs are always welcome! We could add a warning Tip at the end of the @islands/excerpt section warning about this more explicitly.