Blog Data

Ce contenu n’est pas encore disponible dans votre langue.

The Starlight Blog plugin exposes blog-wide data about posts and authors in your project that you can use to build custom components such as recent-post lists, author summaries, or other blog related widgets. This guide explains how to use Starlight Blog’s data.

What is blog data?

Starlight Blog data is an object containing the information about all the blog posts and authors in your project. It includes information like a list of all the blog authors, a list of all the blog posts, the title of each post, the date it was published, and the author.

Using blog data

The posts property contains an array of all the blog posts in your project while the authors property contains an array of all the authors.

You can access this data from Astro.locals.starlightBlog in components rendered as part of a Starlight page, including MDX pages and custom pages using the <StarlightPage> component.

The Starlight Blog plugin exposes this data similarly to Starlight’s own Astro.locals.starlightRoute route data.

When using multiple blog instances, Astro.locals.starlightBlog is not available. Use Astro.locals.starlightBlogs instead.

---
const { posts, authors } = Astro.locals.starlightBlog
//        │       └─ The list of all blog authors
//        └─ The list of all blog posts
---

This can be useful for example to create a widget that lists recent blog posts with their word count on your homepage:

<ul>
  {
    Astro.locals.starlightBlog.posts.slice(0, 5).map((post) => (
      <li>
        <a href={post.href}>{post.title}</a>
        <em>({post.metrics.words.total} words)</em>
      </li>
    ))
  }
</ul>

Preview

Sequantur quaeritis tandem (231 words)
Vario nunc polo (249 words)
Mihi terrae somnia (304 words)
Achivi amans (fr) (322 words)
Ipsum nunc aliquet (322 words)

To render a post using the same preview as blog listing pages, use the <Preview> component.

Another example is to create a list of all the known authors of your blog:

---
const authorNames = Astro.locals.starlightBlog.authors
  .map((author) => author.name)
  .sort((a, b) => a.localeCompare(b, Astro.currentLocale))

const authorList = new Intl.ListFormat(Astro.currentLocale, {
  style: 'long',
  type: 'conjunction',
}).format(authorNames)
---

<p><b>Authors:</b> {authorList}</p>

Preview

Authors: Astro, Bob O'Alice, Fantôme, Ghost et HiDeoo

`starlightBlog`

Type: StarlightBlogData

When multiple blog instances are configured, Astro.locals.starlightBlog is not available and will throw an error. Use Astro.locals.starlightBlogs instead to access the data for a specific blog instance.

The starlightBlog object has the following properties:

`posts`

Type: StarlightBlogPostData[]

A list of all the blog posts in your project ordered by descending publication date.

Each post has the following properties:

`title`

Type: string

The title of the blog post.

`href`

Type: string

The link to the blog post.

`createdAt`

Type: Date

The date of the blog post.

`updatedAt`

Type: Date | undefined

The last update date of the blog post. It is only defined if the lastUpdated frontmatter field is specified and is a date.

`draft`

Type: boolean

Whether the blog post is a draft. Draft blog posts are only visible in development mode.

`featured`

Type: boolean

Whether the blog post is featured.

`cover`

Type: { alt: string; image: ImageMetadata | string } | { alt: string; dark: ImageMetadata | string; light: ImageMetadata | string } | undefined

The optional cover image of the blog post.

Based on how the cover image is defined in the frontmatter of the blog post, it can either be a single image or a pair of images for dark and light themes. Local images are imported and transformed into metadata while remote images are defined as a string URL that you can pass as a src to <Image/> or getImage().

Check the Starlight Blog <Cover> component to see an example of how to use the cover image or learn more about images in content collections in the Astro docs.

`entry`

The Astro content collection entry for the blog post which includes frontmatter values at entry.data.

entry: {
  data: {
    description: string | undefined
    // etc.
  }
}

Learn more about the shape of this object in Astro’s Collection Entry Type reference.

`authors`

Type: StarlightBlogAuthorData[]

The list of authors of the blog post.

`tags`

Type: { label: string; href: string; }[]

The list of tags of the blog post.

Each tag has the following properties:

`label`

Type: string

The label of the tag.

`href`

Type: string

The link to the tag page.

`metrics`

Type: { readingTime: { minutes: number; seconds: number; }; words: { rounded: number; total: number; }; }

The metrics of the blog post.

`readingTime`

Type: { minutes: number; seconds: number; }

The estimated reading time of the blog post.

`minutes`

Type: number

The estimated reading time of the blog post in minutes, rounded up to the nearest minute.

`seconds`

Type: number

The estimated reading time of the blog post in seconds, rounded up to the nearest second.

`words`

Type: { rounded: number; total: number; }

The word count of the blog post.

`rounded`

Type: number

The word count of the blog post rounded up to the nearest multiple of 100.

`total`

Type: number

The total word count of the blog post.

`authors`

Type: StarlightBlogAuthorData[]

An unordered list of all the known authors in your blog.

`starlightBlogs`

The starlightBlogs map is keyed by blog prefix and contains all the blog data for each blog instance with values of type StarlightBlogData.

---
const news = Astro.locals.starlightBlogs.get('news')

if (!news) {
  throw new Error('Missing news blog data.')
}

const { posts, authors } = news
//        │       └─ The list of all authors for the 'news' blog instance
//        └─ The list of all posts for the 'news' blog instance
---

`StarlightBlogAuthorData`

Blog post authors are represented by a StarlightBlogAuthorData object with the following properties:

`name`

Type: string

The name of the author.

`title`

Type: string | undefined

The optional title of the author.

`url`

Type: string | undefined

The optional URL to link the author to.