@igor.dvlpr/astro-post-excerpt

Post Excerpt component for 🚀 Astro

⭐ An Astro component that renders post excerpts for your Astro blog - directly from your Markdown files. Astro v2+ collections are supported as well! 💎
Works with all 3 major versions of Astro!

Now featured on Astro's official Integrations library 😍

_{<PostExcerpt /> component generated excerpt}

💖 Support further development

I work hard for every project, including this one and your support means a lot to me!
Consider buying me a coffee. ☕
Thank you for supporting my efforts! 🙏😊



@igorskyflyer

🕵🏼‍♂️ Usage

Install it by executing:

npm i -D "@igor.dvlpr/astro-post-excerpt"

then import it into your project:

PostPreview.astro

import PostExcerpt from '@igor.dvlpr/astro-post-excerpt'

const { post } = Astro.props

<article>
{ /* other markup */ }
  <p class="post-excerpt">
    <PostExcerpt post={post} words={20} addEllipsis={false} />
  </p>
{ /* other markup */ }
</article>

❗ NOTE: if you get a build error "unknown file extension ".astro" for @igor.dvlpr/astro-post-excerpt", you'll need to update your astro.config.mjs file and add the following property:

vite: {
    ssr: {
      noExternal: ['astro', '@igor.dvlpr/astro-post-excerpt'],
    },
  }

See #3820 for more information.

If you have migrated your Astro site to v2+ you can now use Collections for your posts loop. This component works with both v2+ and versions prior v2.

If you're upgrading this component while keeping your Astro installation <2, everything should work as expected since the introduced changes are backwards-compatible.

In case of an issue, submit it on the component's Issues page. You should provide a concise explanation of the issue you're facing and sample code - if applicable.

🤹🏼‍♂️ Options

post

post: AstroMarkdownFile | AstroCollectionEntry

required , represents the post whose excerpt you want to generate and render. You should insert this component inside your posts loop:

• for Astro >=2, obtained via:

  • getCollection()- for posts loop,

  • getEntryBySlug() - for single posts retrival,

• for Astro <2, obtained via Astro.glob().

If this prop is not supplied or not valid, the component will throw an error.

Types AstroMarkdownFile and AstroCollectionEntryare artificial and they correspond to MarkdownInstance<Record<string, any>> and CollectionEntry<T> respectfully.

words

words?: number

optional, represents the number of words the generated excerpt should have in total. Be aware that the prop maxLength has precedence over this prop but you can use both props simultaneously.

Defaults to 40.

If this prop is not supplied or not valid, a warning will be output to the console.

maxLength

maxLength?: number

optional, represent the max length of the generated excerpt. Be aware that this prop has precedence over the words prop but you can use both props simultaneously.

Defaults to 0 (unlimited).

If this prop is not supplied or not valid, a warning will be output to the console.

addEllipsis

addEllipsis?: boolean

optional, controls whether an ellipsis should be appended to the post excerpt. Defaults to true.

If this prop is not valid, a warning will be output to the console.

smartEllipsis

smartEllipsis?: boolean

optional, controls whether the appended ellipsis should be aware of how the excerpt ends, i.e. if the excerpt ends with a punctuation symbol the ellipsis won't be appended. Defaults to true.

Note: punctuation symbols that this component is aware of are:

• "."
• ","
• "?"
• "!"
• ";"
• "…"

If this prop is not valid, a warning will be output to the console.

ellipsis

ellipsis?: string

optional, controls the ellipsis string that should be appended to the post excerpt. Defaults to "…".

If this prop is not valid, a warning will be output to the console.

headings

headings?: PropHeadings

optional, controls whether the leading post headings should be stripped or preserved. Defaults to "PropHeadings.Intact".

Possible values:

• Intact - leave the headings intact,

• TextOnly - remove Markdown code but keep the headings text,

• None - remove the headings completely.

If this prop is not valid, a warning will be output to the console.

renderer

renderer?: PropRenderer

optional, controls the rendering of the post excerpt. Defaults to "PropRenderer.Text".

Possible values:

• Text - render post excerpts as simple text, no HTML entities supported,

• Html - render post excerpts as HTML, HTML entities supported,

• Hybrid - render post excerpts as simple text but allow HTML entities as well.

If this prop is not valid, a warning will be output to the console.

❗ Note: due to the underlying changes in Astro v2+, posts are retrieved as Markdown only, thus, the options PropRenderer.Html and PropRenderer.Hybrid will yield the same result in Astro v2+, i.e. the option PropRenderer.Html will behave as PropRenderer.Hybrid since there are no HTML tags to render, only HTML entities. Astro <2 is unaffected by this.

✨ Changelog is available here: CHANGELOG.md.